stereOS: a NixOS image that gives an AI agent its own user, PATH and daemons
A Linux based operating system hardened and purpose built for AI agents
At a glance
- What is it?
- stereOS builds bootable Linux images, called mixtapes, that pair a minimal NixOS system with an agent harness such as opencode. The interesting part is the boundary it draws around the agent user, not the agent itself.
- Who is it for?
- Adopt stereOS if you already build with Nix flakes and want an agent process confined to a dedicated agent user with a restricted PATH, rather than a container you hand-assemble. Skip it if you need a stable option surface: two custom NixOS options is the whole documented configuration API, and the README points at stereos.ai for documentation that is not in the repository.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Nix, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: an agent process that needs a machine, not a container
Most agent setups start as a container image and a shell script. That works until the agent needs a persistent workspace, a system daemon that supervises it, or a boot path that does not depend on a container runtime being present. stereOS takes the opposite route: it produces a bootable Linux system image in which the agent is a first-class user. The README describes the project as "a Linux based operating system hardened and purpose-built for AI agents", and the repository is written in Nix, so the whole machine is a build output rather than a hand-configured host. The audience is narrow and specific. If you are running an agent on your laptop and closing the lid when you are done, this is more machinery than the task requires. If you are provisioning a VM per agent, or you want to hand someone a disk image that already contains the harness, the packaging is the point.
Mixtapes: the agent binary is the variable, the system is the constant
stereOS calls its machine images mixtapes. A mixtape bundles a hardened, minimal Linux system with a named agent harness. The README lists one entry in the table: opencode-mixtape, which ships the opencode binary and expects either ANTHROPIC_API_KEY or OPENAI_API_KEY to be present. The mechanism is small enough to state in one line: each mixtape appends its agent package to stereos.agent.extraPackages, which adds the binary to the agent user's restricted PATH. That is the whole trick, and it is a good one. The agent does not get installed into a general-purpose environment where every tool on the host is reachable. It gets a PATH that the image author controls. A -dev variant of each mixtape includes profiles/dev.nix for local SSH key injection, which is the escape hatch for development rather than a production default. The table has exactly one row today, so the mixtape concept is currently a pattern with a single instance. Whether more harnesses appear is a question the repository does not answer.
Two users, two daemons, and a workspace path
The system layout is the part worth reading closely. There is an admin user and group for administrative operations, with a home at /home/admin. There is a separate agent user and group, with a workspace at /home/agent/workspace. Two external daemons handle the runtime: stereosd, described as the stereOS system daemon, and agentd, described as the agent management daemon. The README frames them as "orchestration daemons handling agent lifecycle and acting as a control plane for agent operators". Both arrive as flake inputs from separate repositories, each providing a NixOS module and an overlay. That separation is deliberate and it has a cost: the modules live outside this repository, so the option surface you actually configure is split across three codebases. The README does not document the options that services.agentd and services.stereosd expose. If you need to know what agentd does with a workspace, or how stereosd decides an agent has failed, the answer is in another repository, not here.
Four build attributes, four different boot stories
The image formats are not interchangeable, and the README is explicit about why. Raw EFI is built with system.build.raw and produces stereos.img, described as the canonical artifact and bootable under Apple Virt Framework. QCOW2 comes from system.build.qcow2, is derived from the raw image via qemu-img convert, and targets QEMU/KVM. Kernel artifacts come from system.build.kernelArtifacts and produce bzImage, initrd, cmdline and init for direct-kernel boot that bypasses UEFI and GRUB. The fourth is different in kind. packages.<system>.<mixtape>-lambda-microvm-source produces a Dockerfile source zip for AWS Lambda MicroVM image creation. The README states plainly that this bundle "is not a full stereOS VM image": it packages stereOS userspace into a Dockerfile-based rootfs because Lambda MicroVM images are created from Dockerfile application sources, not custom kernel or disk artifacts. That is an honest limitation stated up front, and it means the Lambda path gives you the userspace and the agent, not the kernel hardening of the other three formats.
Getting a build out: flake attributes and mkDist
You build with Nix, and the README names the attributes rather than a wrapper command. The raw disk is at system.build.raw, the QCOW2 at system.build.qcow2, kernel artifacts at system.build.kernelArtifacts, and the Lambda source at packages.<system>.<mixtape>-lambda-microvm-source. For a publishable set, lib/dist.nix:mkDist assembles every format into one directory, adds zstd-compressed variants built with -19 -T0, and writes a mixtape.toml manifest containing SHA-256 checksums and file sizes for each artifact. The README shows the resulting layout: stereos.img, stereos.img.zst, stereos.qcow2, stereos.qcow2.zst, bzImage, initrd, cmdline, init, and mixtape.toml. The checksum manifest is the piece that makes this usable for distribution, because a consumer can verify a downloaded image against a file that shipped alongside it. Configuration is two options. stereos.ssh.authorizedKeys is a listOf str defaulting to [], and the README notes it covers both admin and agent users and is "useful for development purposes". stereos.agent.extraPackages is a listOf package defaulting to [], and it is the option mixtapes append to. There is no documented option for restricting network egress, for resource limits, or for the agent's shell environment beyond PATH.
Where this is the wrong tool
The configuration surface is the first problem. Two custom options is a thin API for something described as a control plane. Anything you want beyond authorized keys and extra packages has to be expressed as ordinary NixOS configuration, which means you are now maintaining a NixOS system on top of a project that already wraps NixOS. That is a real cost, and the README does not pretend otherwise. The second problem is the documentation split. The homepage is stereos.ai and the README links there for downloads and documentation, but the repository itself documents the options, the image formats and the distribution layout only. The daemons are in separate repositories. If you are evaluating this for a team, the material you need to judge operational behaviour is not in the repository you are reading. The third is the licence. The repository metadata reports NOASSERTION, which means no licence could be determined from the repository contents. You cannot reason about redistribution of a built image, or about the terms attached to the agentd and stereosd inputs, from what is published here. That is a blocking question for commercial distribution, not a footnote.
The alternative you are probably already using
The obvious comparison is a container image plus a runtime, which is how most agent deployments are assembled today. The difference in approach is where the boundary sits. A container gives the agent a filesystem namespace and a process tree inside a host kernel, and the agent user is usually root inside that namespace. stereOS gives the agent a separate Linux user on a real system, with a restricted PATH and a workspace directory, supervised by daemons that are part of the image. That changes what a compromise looks like. In the container case, escaping the namespace is the failure mode. In the stereOS case, the agent user is already outside the namespace model, so the question becomes what that user can reach on the host, and the PATH restriction is the documented answer. The trade is portability for a clearer privilege story. A container runs on your laptop, your CI runner and your cloud of choice without a build step that produces a disk image. stereOS produces a disk image, and the README's formats are all VM-oriented or Lambda-specific. If your deployment target is a Kubernetes cluster, the container is the shorter path, and stereOS is not trying to compete there.
Maintenance, upgrades and what to verify
Upgrade cost is mostly the cost of Nix. The flake pins nixpkgs to nixos-26.05 and pulls agentd, stereosd and dagger as inputs from their own repositories, so a rebuild is only reproducible to the extent those inputs are pinned in your lock file. The most recent release listed is 2026.03.04.0, and the repository's last push is dated 2026-09-02, so releases and commits are not moving in lockstep. The zstd compression level of -19 with -T0 in mkDist is a deliberate choice: maximum compression, all cores. It will make release builds slow, and the README does not state how slow. If you build images on a schedule, that is a cost you should measure before you commit to it. On licence, the NOASSERTION signal means you should read the repository licence file directly and check the terms of the agentd and stereosd inputs separately before you redistribute a mixtape or bake one into a product. Before adopting, verify three things: that the opencode binary and the API key handling match how you intend to authenticate, that services.agentd and services.stereosd expose the lifecycle controls you need, and that the Lambda MicroVM source bundle's Dockerfile-based rootfs meets whatever isolation requirement drove you to look at this project in the first place.
Editorial conclusion
Adopt stereOS if you already build with Nix flakes and want an agent process confined to a dedicated agent user with a restricted PATH, rather than a container you hand-assemble. Skip it if you need a stable option surface: two custom NixOS options is the whole documented configuration API, and the README points at stereos.ai for documentation that is not in the repository. Before building, check the licence terms, since the repository reports NOASSERTION, and confirm that the agentd and stereosd flake inputs resolve at the revisions you intend to pin.
Community notes