stereOS ships one mixtape and the Makefile defaults to another

One mixtape is documented and the Makefile defaults to another

A mixtape is the unit this project builds: a machine image bundling a minimal hardened Linux with a specific agent harness. The mixtapes table has exactly one row, `opencode-mixtape`, carrying the `opencode` binary and expecting either an Anthropic or an OpenAI key. The Makefile at the root of the repository sets its default differently. A variable named `MIXTAPE` defaults to the value `coder`, and all five build targets derive their flake attribute from it, so a plain `make dist` or `make build` produces a `coder` image that the readme never describes. The mechanism that adds a harness is small and worth noting: each mixtape appends its agent package to `stereos.agent.extraPackages`, an option that adds the binary to the agent user's restricted PATH. A `-dev` variant of each mixtape additionally includes a development profile for local SSH key injection, so the dev and production artefacts differ by one profile file.

The agent gets its own user and a restricted PATH

The system is described as minimal, with a few orchestration daemons handling agent lifecycle and acting as a control plane for agent operators, and the identity model is the concrete part. There is an `admin` user and group for administrative operations with a home at `/home/admin`, and an `agent` user and group for the agent to assume with a home at `/home/workspace`. Two daemons sit alongside them, `stereosd` as the system daemon and `agentd` as the agent management daemon, each in its own repository and each contributing a NixOS module and an overlay. The restricted PATH is the detail that makes the model coherent: the agent binary is added to the agent user's path and not to a global one, so a process running as the agent does not see the administrative toolset by default. It is a boundary expressed in the system configuration rather than in a permission check, which is the stronger of the two forms.

Access is an SSH key list that defaults to empty

The project declares two NixOS options and both have empty defaults. One is `stereos.ssh.authorizedKeys`, a list of strings holding SSH public keys for the admin and agent users, and the description calls it useful for development purposes. The other is `stereos.agent.extraPackages`, a list of packages added to the agent's restricted path. The SSH option being described as a development convenience is the part to sit with, because the same option is how an operator gets into a running image. An empty default is the right choice for an artefact nobody should be able to reach until a key is supplied, and the real question is what happens on the machines you did not build yourself. If a fleet of these images is provisioned with a shared development key, then every one of them shares an administrative path, and the readme's phrasing makes that look like a normal setup. Provisioning access per host, with a distinct key per image and a way to rotate one, is the part the two-option surface does not give you.

Four image formats, and the fourth is not an image

The build table lists four outputs. The raw EFI format is the canonical artefact, a disk image that boots on Apple's virtualisation framework. QCOW2 is derived from the raw one with a conversion tool and targets QEMU with KVM. Kernel artefacts give a kernel, an init RAM disk, a command line and an init path, for direct-kernel boot that bypasses both UEFI and the bootloader. And a Lambda MicroVM source bundle is a Dockerfile source zip, produced under a per-mixtape attribute, whose stated purpose is creating an AWS Lambda MicroVM image. The document then says what that last one is not: it is not a full stereOS VM image, and it packages the userspace into a Dockerfile rootfs bundle because Lambda MicroVM images are created from application sources rather than from custom kernel or disk artefacts. So a reader who wants the Lambda path has to understand that they are getting a userspace and not the kernel, the bootloader and the image format that the other three rows deliver.

Every artefact gets a checksum in a manifest, and the build is impure

Distribution is handled by a helper in the library directory, and the output layout is worth reading as a contract. The result directory holds the raw disk, a zstd-compressed copy of it, the QCOW2 image and its compressed variant, the kernel, the init RAM disk, the kernel command line, the init path, and a `mixtape.toml` manifest. Compression is set to level 19 with all cores, which is the slow and small end of the trade, appropriate for artefacts you publish rarely. The manifest carries a SHA-256 checksum and a file size for every artefact, so a consumer can verify what it downloaded without trusting the transport. The build itself is driven by `nix build` calls that all pass `--impure`, and the Makefile requires an architecture variable for every image target, failing with a message naming the two accepted values. Requiring it explicitly is a small guard against silently producing the wrong architecture.

The build depends on four flake inputs, and two of them are first-party

The external dependencies table is short and mostly first-party. Two inputs are the daemons, each pointing at a repository under the same organisation and each providing a NixOS module plus an overlay. One is nixpkgs, pinned to a specific release channel rather than to a commit, and the other is the CI engine, also under first-party control. So of the four inputs, two are the project's own services, one is the package set and one is the build driver, and the pinning is mixed: nixpkgs is on a channel while the first-party inputs are named without a revision in the table, with the actual revisions living in the lock file that the repository also carries. A lock file is what makes the build repeatable, and its presence alongside a channel pin is the normal arrangement, but it does mean a build reads a channel to resolve a base unless the lock is used, and the table does not say which happens.

The repository is mostly Nix, and the CI runs through a container engine

The recorded primary language is Nix, which tells you the shape of the project before you read anything else. The top level is a flake definition and a lock file, then directories for the shared library, the NixOS modules, the per-agent mixtapes, the profiles including the development one, the image format definitions, the Lambda bundle source, build scripts, and a `.dagger/` directory alongside a `dagger.json`. A Makefile sits on top as the human-facing interface with a help target, grouped under image builds and virtual machine development operations, and the run target checks for a built image and builds the missing pieces before launching through a script. So the build has three layers, Nix expressions at the bottom, a Makefile as the documented interface, and a container-based CI engine that is itself a Nix flake input. The presence of a version policy document and a contributing guide alongside an agents file suggests the project expects outside help.

Editorial conclusion

Read stereOS as an opinionated image recipe rather than a distribution, because that is what the repository is: Nix expressions, two custom options, a build helper, and no release history beyond a single March 2026 tag. The design worth borrowing is the user split, with an administrative account and a separate agent account whose home is a workspace, and the agent binary placed on a restricted PATH for that user only, which is a clearer containment boundary than most agent setups achieve by convention. Two things to check before you build. The documentation names one mixtape, the opencode one, while every Makefile target defaults to a mixtape called coder that the documentation never describes, so the first build you run is not the one the readme explains. And access is by SSH public key with an empty default, which is correct for a machine you control and insufficient for a fleet, so plan how operator access is granted before you have twenty of these running. The newest release is 2026.03.04.0 from 4 March 2026 and the last commit on the default branch main is dated 24 September 2026.

Frequently asked questions

Official sources

1. Issues
2. papercomputeco/stereOS on GitHub
3. Project website
4. README
5. Releases