code-on-incus (coi): run AI coding agents in isolated Incus system containers

What code-on-incus solves, and for whom

An AI coding agent that can install packages, run services and reach the network is useful precisely because it is not confined to a read-only filesystem. That is also the problem. The README frames the pitch as giving every agent its own machine with active defense, and the target user is explicit: developers who run agents in parallel, want persistent environments that survive restarts, and do not want host SSH keys, tokens or environment variables inside the agent-controlled container. The design assumption is that the agent should behave like it is on a real server, while the host stays out of reach. If you only ever run one agent on a throwaway directory and never give it network access, the machinery here is heavier than the task.

Incus system containers, not application sandboxes

The mechanism is an Incus system container: a full Linux userspace with systemd and native Docker inside, not a namespace-limited process jail. Your project is mounted at /workspace and, per the README, file ownership comes out correct, which is the specific pain the project calls out about Docker's permission handling. Credential isolation is the default rather than an opt-in: SSH keys, .env files, Git tokens and host environment variables are not exposed unless you explicitly mount them. Network control uses nftables in three modes, and the defense layer is described as kernel-level monitoring that catches reverse shells, C2 connections, data exfiltration, DNS tunneling and credential scanning, with auto-pause on HIGH severity and auto-kill on CRITICAL. That is a real architectural commitment: detection lives below the agent, so the agent cannot simply disable a userspace watchdog. The cost is that coi is not a self-contained binary in the security sense. It links libsystemd via cgo for NFT monitoring, and the Makefile's dependency check calls out pkg-config and libsystemd headers on Linux. Audit output is JSONL for forensics, and supply-chain protection is handled by mounting Git hooks and IDE configs read-only, which prevents an agent from rewriting the hooks that gate your commits.

Installing coi and running a first session

The README gives a three-command path. The installer script is fetched from the master branch and piped to bash, so read it first if you care about what lands on your machine. The second command builds the base image and is the slow step: the README says first time only, roughly 5 to 10 minutes.

curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash
coi build

After the image exists, change into any project directory and start a session. The README states that the project appears at /workspace inside the container, workspace changes are saved back to the host, and Docker and gh are available inside.

cd your-project
coi shell

If you are opening a repository you do not trust, the README points at the hardened preset instead of the default shell. It restricts the network, masks workspace secrets, uses an ephemeral container, disables SSH-agent forwarding and enables live threat monitoring with auto-pause and auto-kill. It also overrides a weaker global config, so a global open mode still becomes restricted.

coi shell --profile hardened
coi profile info hardened

Tool selection is config-shaped rather than a per-command flag. The README shows a TOML block that sets the tool name and permission mode, and notes the file can live at ~/.coi/config.toml or ./.coi/config.toml.

[tool]
name = "claude"
permission_mode = "bypass"

The permitted values listed are claude, codex, opencode, pi and omp for name, and bypass or interactive for permission_mode. Note the second value carefully: bypass means the agent runs autonomously. Profiles are the reusable layer on top, and the README gives three commands for them.

coi shell --profile rust-dev
coi profile create rust-dev
coi profile list

A profile bundles image, tool, resource limits, mounts, network mode, build scripts and AI-agent instructions, supports inheritance through inherits = "parent", and can carry its own build scripts. The README points to the Profiles wiki page for the full schema, which is where you should look before writing one by hand.

Where coi gets in the way

The dependency on Incus is not incidental. coi orchestrates containers that something else has to run, so on Linux you need Incus installed and working, and the README sends macOS users to Colima or Lima through a separate macOS Setup wiki page rather than claiming native support. The comparison table in the README concedes the point directly: it lists runs on Linux natively as Yes for coi and notes that Docker Sandbox is microVM only on macOS and Windows. If your team is standardized on macOS laptops, this is a host setup project before it is an agent tool. There is also a build-time constraint for anyone compiling from source: the Makefile states that coi links libsystemd via cgo for NFT monitoring, so pkg-config and libsystemd headers are required on Linux. The Makefile's own dependency check warns that running sudo make strips PATH, which is a common way to hit a confusing Go-not-found error when Go was installed per-user. On the detection side, auto-pause and auto-kill are policy decisions made for you. A false positive on a CRITICAL classification kills the container, and the README does not document a dry-run mode or a way to review a detection before the kill happens. For a long-running agent doing legitimate network work, that trade-off deserves a test run on a scratch project before you point it at anything that matters.

How coi differs from a Docker-based agent sandbox

The obvious alternative is running the agent in a Docker container. The difference is what the agent gets. A Docker container typically hands the agent a minimal image, a non-root user and a bind mount, and the agent cannot install a system service without rebuilding the image. coi uses an Incus system container, so the agent has root, systemd and Docker inside its own machine, and can run cron or start services the way it would on a server. The second difference is where detection runs. A Docker-based setup usually has no network monitoring beyond whatever you configure yourself, while coi's README describes nftables-based kernel-level monitoring with automated pause and kill responses. The third is credential handling: the README claims credential isolation is the default here, partial for Docker Sandbox and absent on bare metal. The trade-off runs the other way too. Docker is already on most developer machines and needs no separate container manager, whereas coi asks you to install and maintain Incus and, on macOS, a Linux VM underneath it.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-10, so the codebase is moving. The release cadence visible in the changelog is brisk: v0.11.1 and v0.11.2 both landed on 2026-08-11, and v0.12.0 followed on 2026-09-09. Frequent releases are good for fixes and bad for config churn, and this project has a lot of config surface: a global config.toml, per-profile config.toml files, a JSON schema directory in the repository and a wiki page for the profile schema. Budget time for reading the changelog before upgrading, because a profile you wrote against one release may need edits against the next. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence, but it is not legal advice, and if you redistribute coi inside a product you should have someone confirm the notice requirements. Note also that the install script pulls from the master branch rather than a tagged release, so pinning to a specific version means building from source with the Makefile instead.

Editorial conclusion

Adopt coi if you already run Incus on Linux and want agent isolation with root, Docker and systemd inside the box, and you accept that the first image build takes roughly 5 to 10 minutes and that the security posture depends on the Incus host. Skip it if you want a single-binary sandbox with no host-level dependency, or if you are not prepared to read the profile config.toml before trusting the hardened preset. Before rolling it out, run coi profile info hardened and confirm exactly which mounts, network mode and SSH-agent forwarding that profile disables on your machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mensfeld/code-on-incus on GitHub
4. README
5. Releases