Code on Incus (coi)
Give each AI coding agent its own isolated machine with root, Docker, systemd — and active threat defense.
- Source repo
- coipond/coi
- Stars
- ★ 759
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Go
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers running multiple AI agents in parallel on the same project who need fully isolated sessions that cannot leak into each other
- Not a fit if
- Windows users: no Windows support is mentioned
- Teams unwilling to install and maintain Incus themselves
- Users who need Aider or Cursor: not yet supported
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
code-on-incus (coi) is an open-source (MIT) Go CLI that runs AI coding agents — Claude Code, Codex CLI, opencode, pi, omp — inside their own Incus system containers. Each container is a full OS with root, systemd, and native Docker, so agents install packages and run services like on a real server while remaining unable to touch the host or see credentials. Kernel-level active defense uses nftables to catch reverse shells, C2 connections, exfiltration, and DNS tunneling in real time, auto-pausing on HIGH and auto-killing on CRITICAL threats. Workspace files and session history are always persisted, and credentials never enter the container unless explicitly mounted. The deployment boundary is a Linux host with Incus (macOS works via Colima/Lima); a single coi shell command starts a coding session.
coi creates an Incus system container keyed by hash(workspace, session_name), mounts the project at /workspace with correct file ownership, and runs the configured AI tool (claude/codex/opencode/pi/omp) with bypass or interactive permission_mode from config.toml. For security, kernel-level monitoring (three nftables network modes, DNS pinning, egress and per-host port controls) detects threats in real time and responds automatically — auto-pause on HIGH, auto-kill on CRITICAL — logging every event as JSONL that coi audit can stream into a SIEM or jq. Profiles bundle image, tool, resource limits, mounts, network mode, and agent instructions into inheritable templates; the built-in hardened preset applies restricted networking, secret masking, an ephemeral container, and no SSH-agent forwarding. coi run --prompt executes prompts headlessly for automation with host cron (e.g., nightly dependency updates and PRs); prompts are honored only from trusted-scope config (~/.coi/config.toml), so cloned repos cannot inject them.
- Developers running multiple AI agents in parallel on the same project who need fully isolated sessions that cannot leak into each other
- Anyone opening an untrusted third-party repo who wants to inspect it safely via
coi shell --profile hardenedunder maximum lockdown - Teams worried about agents reaching SSH keys, .env files, or Git tokens, who want credentials to never enter the agent environment by default
- Engineers who want real-time alerts and forensics on agent behavior, piping
coi auditJSONL logs into a SIEM - Maintainers needing unattended automation via cron plus
coi run --prompt-namefor nightly dependency updates, tests, and PRs - Users who want persistent dev environments that survive restarts, keeping installed packages and resumable session history
How do you install or deploy this agent?
Requires Linux with Incus installed (macOS works via Colima/Lima — see the wiki macOS Setup Guide). Install: curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash. Build the base image on first use (~5–10 min): coi build. Then start coding from any project directory with coi shell.
How do you use this agent?
Run coi shell in a project directory to start an interactive session (Claude Code by default). Configure tools and permission modes in ~/.coi/config.toml or a per-repo .coi/config.toml (e.g., [tool] name = "codex", permission_mode = "bypass" for autonomous or "interactive" to ask first). Common commands: coi run -- npm test (run any command in the sandbox, output streamed, exit code propagated), coi run --prompt "..." (headless prompt execution), coi run --prompt-name nightly (run a named prompt from the config [prompts] table, cron-friendly), coi shell --profile rust-dev (launch a named profile), coi shell --profile hardened (maximum lockdown preset), coi monitor (live security dashboard), coi top (per-container resource usage), coi attach (join a running session), coi audit (stream the JSONL threat-event log), and coi shutdown / kill / clean for container management.
What are this agent's strengths and limitations?
- Real machine, not a locked box: Incus system containers give agents root, systemd, and native Docker — packages, services, and cron work like a server, with correct host file ownership and no chown
- Active defense, not just a wall: kernel-level (nftables) monitoring catches reverse shells, C2, exfiltration, DNS tunneling, and credential scanning, with auto-pause on HIGH and auto-kill on CRITICAL
- Clear credential model: SSH keys, .env files, and host env vars never enter the container unless explicitly mounted; sharing uses socket forwarding or short-lived tokens instead
- Parallel agents stay fully isolated on the same project, each slot with its own home directory; workspace files and session history always persist and are resumable
- Profiles support inheritance and the zero-setup
hardenedpreset overrides weaker global config, making untrusted-code inspection safe with one flag
- Depends on Incus and a Linux host; macOS only works indirectly via Colima/Lima, and Windows support is not mentioned
- First
coi buildtakes 5–10 minutes, and users must install and maintain Incus themselves - Headless prompt mode currently supports only the claude tool and requires permission_mode = "bypass"; Aider and Cursor are not yet supported
- Automated kill/pause responses can interrupt a working agent, so users must understand threat tiers and network modes (restricted/allowlist/open)
- The README provides no performance benchmarks or false-positive rates for threat detection, so effectiveness must be evaluated independently
How does this agent compare with similar options?
The README includes a comparison table: versus Docker sandboxes, code-on-incus offers default credential isolation, kernel-level (nftables) real-time threat detection with auto-kill/auto-pause on reverse shells and exfiltration, three network isolation modes, and JSONL audit logging, while Docker sandboxes only partially isolate credentials and offer none of these; bare metal offers no isolation or detection. The author chose Incus (a modern LXD fork) system containers over Docker application containers for a full init system and second-level startup.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Code on Incus (coi) This agent | 66 · Some gaps | CLIFree + model costs | ★ 759 | 1d ago | Go | Codex · Claude Code |
| sandboxed.sh | 52 · Major gaps | Self-hosted serviceFree + model costs | ★ 534 | today | Rust | Codex · Claude Code |
| Plannotator | 78 · Good | CLIFreemium | ★ 9.6k | today | TypeScript | Codex · Claude Code |
| NeuroSquad Terminal Dashboard | 76 · Good | CLIFree + model costs | ★ 62 | 11d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows default credential isolation (SSH keys/env never enter the container), three network modes, JSONL audit logging, and trusted-scope enforcement (project-level [prompts] ignored) — good. Deductions: install.sh runs via curl|bash and writes /etc/sudoers.d/coi-nft (NOPASSWD nft), a significant host privilege change; permission_mode can be bypass and headless defaults to bypass with auto-approval; auto-kill of containers is a deliberate external effect; rollback relies on snapshots documented only in the wiki without source-level evidence here; MIT with named copyright holder is clear.
CI covers 20+ integration groups with race detector, coverage, parallel unit/integration lanes — self-consistent. Failure messages are asserted in tests (no-tmux suggests --bash, clear failures without sudoers, coi health). Deductions: heavy dependence on external Zabbly repo, Ubuntu/Colima image downloads; CI itself documents transient network failures requiring retries; no lock/fallback availability strategy.
Audience and scenarios are well described (developers running AI agents, parallel agents, inspecting untrusted repos); hardened preset, profile inheritance, Linux/Incus and macOS Colima support with wiki guides. Deductions: prompt mode currently supports only claude with bypass — a narrow boundary, though documented; threat-detection trigger precision (thresholds/false positives) can only be inferred from test names, rules not visible in provided files.
README-to-wiki information architecture is excellent; rich command examples; full MIT text, three-step install, and limitations (macOS via Colima, no-sudoers path) documented. Deductions: no CHANGELOG/version-history file in the repository (only a release badge); FAQ/Troubleshooting are external wiki links unverifiable from these files; the installation test workflow is disabled (.disabled).
Output usability is supported: JSONL audit for SIEM, exit-code propagation, coi top/monitor/audit. Marginal value is high — system containers plus kernel-level threat detection with automated response is uncommon among alternatives. Deductions on cost/benefit: 5-10 min first build, Incus host with nftables/sudo requirements — heavier than a Docker sandbox; detection accuracy is unproven in static review, so benefit partly rests on unverified detection quality.
README claims largely corroborate against CI test groups (threat detection, reverse shells, nftables isolation, #508 no-sudo path, #505 regression all have named tests) and are traceable to wiki pages. Deductions: security claims (auto-kill/auto-pause effectiveness) are corroborated only by test naming, not by implementation code in the provided files; some copy ('killer preset') is marketing language rather than factual statement.
- Installation uses curl | bash and writes a NOPASSWD nft sudoers rule — review install.sh first and understand the host firewall-control grant.
- Headless prompt mode forces bypass permissions; the agent executes without confirmation. Use only on trusted projects and always use --profile hardened for untrusted repos.
- The auto-kill/pause threat detection accuracy is unverified in this static review; both false-positive interruptions and false-negative misses are possible.
- No in-repo CHANGELOG; version tracking depends on GitHub Releases, and the installation-test workflow is currently disabled.
- The provided source files exclude the core Go implementation, so confidence is low; independently verify the security-critical claims (kernel-level detection, automated response) in the actual source and tests before relying on them.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.16.0 Release v0.16.0
Release notes excerpt
Installation Quick Install (Linux) ```bash Install latest version curl -fsSL https://raw.githubusercontent.com/coipond/coi/master/install.sh | bash ``` Manual Installation Download the appropriate binary for your system: Linux AMD64 (x86_64) ```bash wget https://github.com/coipond/coi/releases/download/v0.16.0/coi-linux-amd64 chmod +x coi-linux-amd64 sudo mv coi-linux-amd64 /usr/local/bin/coi ``` Linux ARM64 (aarch64) ```bash wget https://github.com/coipond/coi/releases/download/v0.16.0/coi-linux-arm64 chmod +x coi-linux-arm64 …View on GitHub ↗ -
v0.15.0 Release v0.15.0
Release notes excerpt
Installation Quick Install (Linux) ```bash Install latest version curl -fsSL https://raw.githubusercontent.com/coipond/coi/master/install.sh | bash ``` Manual Installation Download the appropriate binary for your system: Linux AMD64 (x86_64) ```bash wget https://github.com/coipond/coi/releases/download/v0.15.0/coi-linux-amd64 chmod +x coi-linux-amd64 sudo mv coi-linux-amd64 /usr/local/bin/coi ``` Linux ARM64 (aarch64) ```bash wget https://github.com/coipond/coi/releases/download/v0.15.0/coi-linux-arm64 chmod +x coi-linux-arm64 …View on GitHub ↗ -
v0.14.0 Release v0.14.0
Release notes excerpt
Installation Quick Install (Linux) ```bash Install latest version curl -fsSL https://raw.githubusercontent.com/coipond/coi/master/install.sh | bash ``` Manual Installation Download the appropriate binary for your system: Linux AMD64 (x86_64) ```bash wget https://github.com/coipond/coi/releases/download/v0.14.0/coi-linux-amd64 chmod +x coi-linux-amd64 sudo mv coi-linux-amd64 /usr/local/bin/coi ``` Linux ARM64 (aarch64) ```bash wget https://github.com/coipond/coi/releases/download/v0.14.0/coi-linux-arm64 chmod +x coi-linux-arm64 …View on GitHub ↗
FAQ
Which AI tools does it support?
Can the agent reach my SSH keys or environment variables?
Will I lose my work?
What if threat detection kills an agent that was working fine?
coi audit to inspect the JSONL event log, and tune strictness via network modes (restricted/allowlist/open) and profiles.