code-on-incus (coi)

Isolated machines for AI coding agents - with active defense.

COI gives each AI agent its own machine - a full system container with root access, systemd, Docker, and the ability to install anything. Agents work like they would on a real server: run services, manage packages, use cron - without touching your actual system. Files stay correctly owned, no permission hacks needed.

Your credentials stay on the host. SSH keys, environment variables, and Git tokens are never exposed to AI tools unless you explicitly mount them. If something goes wrong, COI catches it - reverse shells, credential scanning, data exfiltration - and pauses or kills the container automatically. No manual intervention needed.

Built by developers, for developers who run AI agents and want to know what those agents are doing. Not a product, not a startup - a tool that does the job.

Who this is for

• You run AI coding agents and want them to have full machine access - root, Docker, package managers, services - without risking your host
• You want to know when an agent does something suspicious, not find out after the fact
• You run multiple agents in parallel and need them isolated from each other
• You want persistent dev environments that survive restarts and reboots, not throwaway containers that lose your setup every time
• You care about your credentials not ending up inside an agent-controlled environment

Table of Contents

• Who this is for
• Supported AI Coding Tools
• Supported Tools (detailed)
• Features
• Quick Start
• Why Incus Instead of Docker or Docker Sandboxes?
• Installation
• macOS Support
• Usage
• Run Scripts and Commands in the Sandbox
• Session Resume
• Persistent Mode
• Configuration
• Profiles
• Resource and Time Limits
• Container Lifecycle & Session Persistence
• Network Isolation
• Security Monitoring
• Security Best Practices
• Snapshot Management
• System Health Check
• Troubleshooting
• FAQ

Supported AI Coding Tools

Currently supported:

• Claude Code (default) - Anthropic's official CLI tool
• opencode - Open-source AI coding agent (https://opencode.ai)
• pi - AI coding assistant (https://pi.dev)
• Codex CLI - OpenAI's coding agent (https://developers.openai.com/codex/cli)

Coming soon:

• Aider - AI pair programming in your terminal
• Cursor - AI-first code editor
• And more...

Tool selection is config/profile-driven:

# ~/.coi/config.toml or ./.coi/config.toml
[tool]
name = "opencode"            # or "claude" (default), "pi", "codex"

coi shell                    # Uses the configured tool (Claude Code by default)
coi shell --profile opencode # Or switch via a profile with [tool] name = "opencode"

Permission mode - Control whether AI tools run autonomously or ask before each action:

# ~/.coi/config.toml or .coi/config.toml
[tool]
name = "claude"              # Default AI tool
permission_mode = "bypass"   # "bypass" (default) or "interactive"

For Claude, bypass maps to --permission-mode bypassPermissions; for codex it maps to --dangerously-bypass-approvals-and-sandbox (the container is the sandbox), and interactive keeps codex's own approval prompts (-s workspace-write -a on-request).

Codex authentication: coi seeds the host's ~/.codex/auth.json into the container (alongside config.toml and AGENTS.md), so log in on the host first with codex login. If the host stores credentials in the OS keyring (no auth.json) or you have never logged in, authenticate inside the container with codex login --device-auth (requires device-auth enablement in your org) or codex login --with-api-key - the plain codex login browser flow does not work inside the container because its OAuth localhost callback is unreachable from the host browser.

See the Supported Tools wiki page for detailed configuration, API key setup, and adding new tools.

Features

Core Capabilities

• Multi-slot support - Run parallel AI coding sessions for the same workspace with full isolation
• Session resume - Resume conversations with full history and credentials restored (workspace-scoped)
• Persistent containers - Keep containers alive between sessions (installed tools preserved)
• Workspace isolation - Each session mounts your project directory
• Slot isolation - Each parallel slot has its own home directory (files don't leak between slots)
• Workspace files persist even in ephemeral mode - Only the container is deleted, your work is always saved
• Container snapshots - Create checkpoints, rollback changes, and branch experiments with full state preservation

Host Integration

• SSH agent forwarding - Use git-over-SSH inside containers without copying private keys ([ssh] forward_agent = true)
• Host port publishing - Publish container TCP ports on the host ([ports] pool for identity-mapped agent-usable ports, [[ports.map]] for fixed services): agent-started dev servers become reachable at localhost:<port>, with per-slot deterministic allocation, a pre-launch conflict check, and coi trust gating for untrusted project configs
• Host socket forwarding - Forward arbitrary host Unix sockets into the container ([[sockets]]) so the host endpoint never enters the container - the building block for credential brokers (mint short-lived tokens on the host, fetch them on demand inside). Untrusted project-config sockets are gated behind coi trust
• Credential catalog - Copy third-party provider credentials into the container via [[credentials]] entries (config or profile): reference a named catalog bundle (bundle = "ollama") or declare an ad-hoc host/container file pair for anything not yet cataloged. claude/opencode/pi's own credential files come from the same built-in catalog. Ad-hoc entries from an untrusted project .coi/config.toml are gated behind coi trust; catalog references carry the same trust level the built-in tool credentials already have
• Environment variable forwarding - Selectively forward host env vars by name (forward_env in config)
• Command-sourced env vars - Mint a fresh secret per session by running a host command at start and injecting its output as an env var ([defaults.env_commands]) - for short-lived API keys/tokens. Trusted-scope config only
• Host timezone inheritance - Containers automatically inherit the host's timezone (configurable via [timezone] config)
• Sandbox context file - Auto-injected ~/SANDBOX_CONTEXT.md tells AI tools about their environment (network mode, workspace path, persistence, etc.). Automatically loaded into each tool's native context system: Claude Code via ~/.claude/CLAUDE.md, OpenCode via the instructions field in opencode.json, pi via ~/.pi/agent/APPEND_SYSTEM.md symlink, Codex via ~/.codex/AGENTS.md (opt out with auto_context = false)

Security & Isolation

• Credential protection - SSH keys, .env files, Git credentials, and environment variables are never exposed unless explicitly mounted
• Privileged container guard - Refuses to start when security.privileged=true is detected, which defeats all container isolation
• Security posture verification - coi health checks seccomp, AppArmor, and privilege settings to confirm full isolation
• Kernel version enforcement - Warns on host kernels below 5.15 that may lack security features for safe isolation
• Real-time threat detection - Kernel-level nftables monitoring detects reverse shells, C2 connections, data exfiltration, DNS tunneling, and credential scanning
• Automated response - Auto-pause on HIGH threats, auto-kill on CRITICAL - no manual intervention needed
• Network isolation - nftables-based restricted/allowlist/open modes block private-network access and exfiltration, with fine-grained egress controls: pin DNS to your own resolver (dns_servers), cap outbound ports globally (allowed_ports) or per-destination (allowed_domains with :ports, and per-host [[network.hosts]] ports) - e.g. "internet open, on the LAN only redmine:443"
• Protected paths - .git/hooks, .git/config, .husky, .vscode mounted read-only to prevent sup