Code on Incus (coi)
Give each AI coding agent its own isolated machine with root, Docker, systemd — and active threat defense.
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.
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
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 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.
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.
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.