Mutiny logo

Mutiny is a young project! If you find the ideas here interesting, please reach out at

There’s a set of git repositories. No bootable system yet, this OS mostly exists as a pile of documents and some broken chroots for now.

This is the main document, here’s a few other documents written currently:

  • A short design document about praxis, the package manager.

  • A longer but unfinished document about the package API, theory.

  • A running list of software that might be of interest for Mutiny.


mutiny - a Linux distribution that aims to be a testbed for interesting system design, forward thinking choices, and fun computing


Mutiny is a project aiming to deliver a Linux distribution that prioritizes a consistent, interesting, and fun to use system. Influenced heavily by minimalist software and and an interest in forward-thinking system design, Mutiny aims to explore alternatives to the hegemony and monotony that makes up most Linux distributions.


This section will outline the intent and approach to design that Mutiny aims to have.

Core concepts

  • Consistency: Unix systems have suffered from a large amount of inconsistencies in maintenance and style in the past decades. Software should be bent to conform, and users should come to expect things are going to be a certain way on a Mutiny system.

  • Alternatives: In the Linux world there is often an acceptance that some of the system just sucks, and it’s just what we’re stuck with. And that’s reasonable in some cases where alternatives don’t exist. However, Mutiny should aim to explore, thoroughly, alternatives.

  • Documentation: The system should be thoroughly documented so that you never need to reference external websites in order to learn about it. Documentation should be consistent, too. This means all documentation should be accessible through man or /usr/share/doc.

Standards adherence

Mutiny should aim to adhere to standards whenever it is possible, and enforce those standards on all software that the system uses. When a standard isn’t good, or we think it is badly designed, we should aim to supersede it with a defined standard of our own. The prime example of a bad standard being replaced in Mutiny is the Filesystem layout, which supersedes the Filesystem Hierarchy Standard and systemd’s file-hierarchy.

Good examples of standards we want to follow would be standards like the XDG Base Directory Specification.

System administration

The state of system administration nowadays can be very fragmented. Most people just search for the documentation online nowadays, finding the manuals to be lacking, or just too archaic.

However this is rarely a problem with *BSD systems. This is because BSD systems, historically, have put more emphasis on good documentation of their systems. Every single aspect of the kernel’s internals, drivers, quirks, etc., is documented in a manpage.

On a large scale, this unity in the system is what Mutiny is striving for. Linux systems have had a tendency to be disjointed at times, as the model which the system is developed in doesn’t usually correspond to the stewardship that comes with the tightly-managed attitude of something like OpenBSD.

Prior art


  • Software

    • Base

      • musl

      • toybox

        • busybox to fill in the cracks, temporarily

      • mksh

        • The long-term plan is to switch to the Oil shell once it is fully functional.

        • This is to be decided, however; mrsh may also be looked into, though it lacks arrays and likely won’t ever have them since they aren’t part of POSIX.

      • execline for system automation

      • s6 and s6-rc for system initialization and supervision

      • snooze for job scheduling

      • mdevd for device handling, firmware loading

      • libressl

      • mandoc

    • Toolchain

Nonessential but otherwise interesting software that would be a good fit to the philosophy can be found on the software page.

Mutiny utilities

  • praxis - a source-based package manager

  • synonym - a utility for managing alternatives

  • commune - utilities for working with the s6 and s6-rc state manager with Mutiny policy

    • commune-snooze - manages scheduled jobs at the system and user scope

    • commune-user - manages the user’s services and states (cf. systemd --user)

    • commune-xinit - manages the user’s Xorg session

Filesystem layout

In the Mutiny layout, there are a few goals:

  • Accomodate some common paths; #!/bin/sh, etc.

  • Remove redundancy. No more /media or /usr, /tmp points to /run/tmp.

  • Embrace the good innovations that have occurred, like /run and the /sbin+/bin merge.

/                           - The root, and root user's home directory.
├── bin                     - System-managed binary files.
├── dev                     - Device files. (devtmpfs)
├── etc                     - System-localized configuration.
├── home                    - User files.
├── include                 - System-managed header files.
├── lib                     - System-managed library files.
├── local
│   ├── bin                 - User-managed binary files.
│   ├── include             - User-managed header files.
│   ├── lib                 - User-managed library files.
│   └── share               - User managed resource files.
│       └── man             - User-managed manual pages.
├── mnt                     - Mounted devices and mountpoints.
├── proc                    - Process information. (procfs)
├── run                     - Runtime files. (tmpfs, directory structure created at boot)
│   ├── tmp                 - Temporary files. (cleared at boot)
│   └── user                - User runtime files.
│       └── 1000            - User's `$XDG_RUNTIME_DIR`. (created at login)
│           └── commune     - User's supervision trees, maintained by `commune` scopes.
│               ├── snooze  - Corresponds to the running supervision tree for user's jobs.
│               │             Maintained by `commune-snooze`.
│               ├── user    - Corresponds to the running supervision tree for the user.
│               │             Maintained by `commune-user`.
│               └── xinit   - Corresponds to the running supervision tree for the user's Xorg
│                             session. Maintained by `commune-xinit`.
├── sbin                    - Symbolic link to `bin`.
├── share                   - Managed resource files.
│   └── man                 - System manual pages.
├── srv                     - Service directories. (git-daemon, httpd)
│   ├── git
│   └── http
├── sys                     - System/kernel information. (sysfs)
├── tmp                     - Symbolic link to `run/tmp`.
├── usr                     - Symbolic link to `.`.
└── var                     - Persistent system data.
    ├── cache               - Cache for system programs.
    │   └── praxis
    │       └── distfiles   - Downloaded source for packages.
    ├── lib                 - Log files for system programs.
    ├── log                 - Databases and other data for system programs.
    ├── run                 - Symbolic link to `../run`.
    └── tmp                 - Persistent yet temporary files, not cleared at boot.

At one point, there was an intent to support cross-compilation, akin to Exherbo’s multiarch design. This has been removed due to a lack of necessity and ultimately, little gain for a lot of pain to take on.

Package design

  • Reasonable command line interface

  • Run (inexpensive) tests by default

  • Libraries

    • See: Gentoo’s eclasses, Exherbo’s exlibs

  • Useful metadata

    • Build dependencies vs. runtime dependencies

    • Licenses

    • Links to documentation

Random notes

(ideally these will disappear and turn into their own sections or pages or what have you)

On languages and internationalization

The insistance of English being "the default language of computing" as a rationale to justify not replacing gettext is rather stupid, when not a bit xenophobic. Asserting default languages of entire fields has real world implications when it gets down to the people using them. There’s a really interesting tendency in the Unix development crowds that have minimalist design tendencies to just ignore this.

Mutiny packages should allow for options to only install whatever languages are going to be used. We can set en_US as the default language that is enabled in packages, but only if we are going to provide complete support to those who speak other languages. There’s an obvious question here as to documentation and support through things like IRC though, and I’m only one person.


A goal should be to ensure that most documentation is mdoc format. s6 is a notable example of a project that doesn’t currently have manpages, though I believe that’s something many people in the community have been wanting.

There’s a few tools written by the main mandoc dev that convert other formats to mdoc, they might be worth looking at.

s6 based stuff

In Mutiny, a goal should be to have the same software powering many scopes of the system. This promotes the ability to have an intimate familiarity with the foundation of your system, and thus an easier introduction to administrating it and doing cool stuff with it. A really good point in which this can be carried out is in s6 and s6-rc.

I have a work in progress implementation of doing this at the xinit level, since it’s definitely possible to do a supervisor as your session manager for Xorg sessions. Furthermore, this should be able to be carried up to the login level. (call it commune-user) This could mean user services for users on the system, akin to systemd’s user scope…​

Software contortions

1. LLVM as a project seems to be suffering from lots of feature creep and could do with some new maintainership and less influence from Google. Notably, they are looking into creating their own libc written in C++ for whatever reason. LLVM seems to be a project carrying a lot of baggage that I’m really not interested in involving with my project. Aside from that, using LLVM, while one of my initial hopes for Mutiny, has proven over time to also be one of the main reasons it has stagnated attempt after attempt. This is pretty disappointing to me as I had really hoped to be one of the first distributions made with a completely non-GNU toolchain.