Code on Incus: Security-Hardened Container Runtime for AI Coding Agents

Security-Hardened Container Runtime for AI Coding Agents with Real-Time Threat Detection Run AI coding assistants (Claude Code, opencode, Aider, and more) in isolated, production-grade Incus containers with zero permission headaches, perfect file ownership, and true multi-session support. Limited Blast Radius: Prepare your workspace upfront, let the AI agent run in isolation, validate the outcome. No SSH keys, no environment variables, no credentials exposed. If compromised, damage is contained to your workspace. Network isolation helps prevent data exfiltration. Your host system stays protected. Security First: Unlike Docker or bare-metal execution, your environment variables, SSH keys, and Git credentials are never exposed to AI tools. Containers run in complete isolation with no access to your host credentials unless explicitly mounted. Proactive Defense: COI doesn't just isolate AI tools — it can actively watch them. Enable the built-in security monitoring daemon ([monitoring] enabled = true ) to detect reverse shells, credential scanning, and large data reads in real time, automatically pausing or killing the container before damage can occur. No manual intervention needed. Think Docker for AI coding tools, but with system containers that actually work like real machines. Watch the BetterStack video about Code on Incus - Supported AI Coding Tools - Supported Tools (detailed) - Features - Quick Start - Why Incus Instead of Docker or Docker Sandboxes? - Installation - macOS Support - Usage - 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 Currently supported: - Claude Code (default) - Anthropic's official CLI tool - opencode - Open-source AI coding agent (https://opencode.ai) Coming soon: - Aider - AI pair programming in your terminal - Cursor - AI-first code editor - And more... Tool selection: coi shell # Uses default tool (Claude Code) coi shell --tool opencode # Use opencode instead 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" See the Supported Tools wiki page for detailed configuration, API key setup, and adding new tools. 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 ) - Environment variable forwarding - Selectively forward host env vars by name ( forward_env in config) - 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 theinstructions field inopencode.json (opt out withauto_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 - Firewalld-based restricted/allowlist/open modes block private network access and prevent exfiltration - Protected paths - .git/hooks ,.git/config ,.husky ,.vscode mounted read-only to prevent supply-chain attacks - System containers - Full OS isolation with unprivileged containers, better than Docker privileged mode - Automatic UID mapping - No permission hell, files owned correctly - Audit logging - All security events logged to JSONL for forensics and compliance Safe Dangerous Operations - AI coding tools often need broad filesystem access or bypass permission checks - These operations are safe inside containers because the "root" is the container root, not your host system - Containers are ephemeral - any changes are contained and don't affect your host - This gives AI tools full capabilities while keeping your system protected # Install curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash # Build image (first time only, ~5-10 minutes) coi build # Start coding with your preferred AI tool (defaults to Claude Code) cd your-project coi shell # Or use opencode instead coi shell --tool opencode # That's it! Your AI coding assistant is now running in an isolated container with: # - Your project mounted at /workspace # - Correct file permissions (no more chown!) # - Full Docker access inside the container # - GitHub CLI available for PR/issue management # - All workspace changes persisted automatically # - No access to your host SSH keys, env vars, or credentials Incus is a modern Linux container and virtual machine manager, forked from LXD. Unlike Docker (which uses application containers), Incus provides system containers that behave like lightweight VMs with full init systems. | Capability | code-on-incus | Docker Sandbox | Bare Metal | |---|---|---|---| | Credential isolation | Default (never exposed) | Partial | None | | Real-time threat detection | Kernel-level (nftables) | No | No | | Reverse shell detection | Auto-kill | No | No | | Data exfiltration alerts | Auto-pause | No | No | | Network isolation | Firewalld (3 modes) | Basic | No | | Protected paths | Read-only mounts | No | No | | Auto response (pause/kill) | Yes | No | No | | Audit logging | JSONL forensics | No | No | | Supply-chain attack prevention | Git hooks/IDE configs protected | No | No | - Linux-first, not Linux-last. Docker Sandboxes' microVM isolation is only available on macOS and Windows. Linux gets a legacy container-based fallback. COI is built for Linux from the ground up because Incus is Linux-native. - No Docker Desktop required. Docker Sandboxes is a Docker Desktop feature. Docker Desktop is not open source and has commercial licensing requirements for larger organizations. COI depends only on Incus - fully open source, no vendor lock-in, no additional runtime. - System containers, not containers-in-VMs. Incus system containers run a full OS with systemd and native Docker support inside - one clean isolation layer. Docker Sandboxes nests application containers inside microVMs, adding architectural complexity. - No permission hell. Incus automatic UID/GID shifting means files created by agents have correct ownership on the host. No chown , no mapping hacks. - Credential isolation by default. Host environment variables, SSH keys, and Git credentials are never exposed to AI tools unless explicitly mounted. - Simple and transparent. No separate daemon, no opaque VM nesting. COI talks directly to Incus - easy to inspect, debug, and extend. # One-shot install curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash # This will: # - Download and install coi to /usr/local/bin # - Check for Incus installation # - Verify you're in incus-admin group # - Show next steps Manual installation: Download the binary from GitHub Releases, make it executable, and move to /usr/local/bin/ . Requires Linux with Incus installed and user in the incus-admin group. See the Incus installation guide for setting up Incus. # Build the default coi-default image (5-10 minutes) coi build # Build without compression (faster iteration) coi build --compression none # Build a custom image via a profile coi profile create my-image --image my-image # Edit .coi/profiles/my-image/config.toml to add a [build] section coi build --profile my-image What's included in the coi-default image: - Ubuntu 22.04 base with Docker (full Docker-in-container support) - mise (polyglot runtime manager) — Python 3, pnpm, TypeScript, tsx pre-installed; add more with mise use go@latest ,mise use ruby@3 , etc. - Node.js 20 LTS (system, for Claude CLI) + npm - Claude Code CLI (default AI tool) + GitHub CLI ( gh ) - tmux, git, curl, build-essential, and common build tools - Modern CLI utilities: fd-find, bat, tree - Debugging tools: strace, lsof - Database clients: sqlite3, postgresql-client, redis-tools - imagemagick for image processing Custom images: Build your own specialized images using profile-based build scripts that run on top of the base coi-default image. See the Image Management wiki page for complete profile-based build workflows. COI works on macOS using Colima or Lima VMs. See the macOS Setup Guide for complete instructions. # Interactive session (defaults to Claude Code) coi shell # Use a different AI tool coi shell --tool opencode # Persistent mode - keep container between sessions coi shell --persistent # Use specific slot for parallel sessions coi shell --slot 2 # Resume previous session coi shell --resume # Run a command in an ephemeral container coi run "npm test" # Attach to existing session coi attach # List active containers and saved sessions coi list --all # Gracefully shutdown / force kill containers coi shutdown coi-abc12345-1 coi kill --all # Cleanup stopped containers and orphaned resources coi clean # Update coi to the latest release coi update --workspace PATH # Workspace directory to mount (default: current directory) --slot NUMBER # Slot number for parallel sessions (0 = auto-allocate) --persistent # Keep container between sessions --resume [SESSION_ID] # Resume from session (omit ID to auto-detect latest for workspace) --continue [SESSION_ID] # Alias for --resume --profile NAME # Use named profile --image NAME # Use custom image (default: coi-default) Most container customization (network mode, mounts, environment variables, SSH agent, monitoring, timezone, resource limits, etc.) is configured via config files or profiles. See the Configuration wiki page for the full reference. See the wiki for detailed documentation: - Container Operations - Container management and low-level operations - File Transfer - Push/pull files between host and containers - Tmux Automation - Automate AI sessions with tmux commands - Image Management - Create and manage custom images - Snapshot Management - Create checkpoints and rollback changes Resume a previous AI coding session with full history and credentials restored: coi shell --resume # Auto-detect latest session for this workspace coi shell --resume= # Resume specific session coi list --all # List available sessions What's restored: Full conversation history, tool credentials, user settings, and project context. Sessions are workspace-scoped — --resume only finds sessions from the current workspace directory. See the Container Lifecycle and Sessions guide for details on how session persistence works. By default, containers are ephemeral (deleted on exit). Your workspace files always persist regardless of mode. Enable persistent mode to also keep the container and its installed packages: coi shell --persistent # Or via config (~/.coi/config.toml) [defaults] persistent = true What persists: - Ephemeral mode: Workspace files + session data (container deleted) - Persistent mode: Workspace files + session data + container state + installed packages, system setup See the Container Lifecycle and Sessions guide for details. Config file: ~/.coi/config.toml [defaults] image = "coi-default" persistent = true [tool] name = "claude" permission_mode = "bypass" # auto_context = true # Auto-inject sandbox context into tool's native system Configuration hierarchy (highest precedence last): - Built-in defaults - User config ( ~/.coi/config.toml ) - Project config ( ./.coi/config.toml ) COI_CONFIG environment variable- Environment variables ( CLAUDE_ON_INCUS_* ,COI_* ) - Operational CLI flags ( --workspace ,--slot ,--persistent ,--resume ,--profile ,--image ) Place a .coi/config.toml in any repository root to auto-configure COI for that project — useful for teams to share container image, environment, and resource limits. See the Configuration wiki page for the full config reference, per-repo setup, profiles, and environment variables. Profiles are reusable container configurations bundling image, tool, limits, mounts, build scripts, context files, and environment into named templates. Each profile is a self-contained directory with its own config.toml and optional supporting files. .coi/profiles/ ├── rust-dev/ │ ├── config.toml # profile config │ ├── build.sh # profile-specific build script │ └── CONTEXT.md # AI agent context (appended to sandbox context) └── python-ml/ ├── config.toml └── setup.sh Example profile config (.coi/profiles/rust-dev/config.toml ): image = "coi-rust" persistent = true context = "CONTEXT.md" forward_env = ["CARGO_HOME"] [environment] RUST_BACKTRACE = "1" [tool] name = "claude" permission_mode = "bypass" [limits.cpu] count = "4" Profile inheritance: Profiles can inherit from a parent using inherits = "parent-name" , so you only override what differs: # .coi/profiles/rust-dev-nightly/config.toml inherits = "rust-dev" image = "coi-rust-nightly" [environment] RUST_CHANNEL = "nightly" Environment maps merge (child keys win, "" clears a parent key). Arrays (mounts , forward_env ) fully replace if the child defines them. Struct sections (limits , tool , network ) deep-merge field by field. Inheritance works across config levels (a project profile can inherit from a user-level profile) and supports chains up to 10 levels with cycle detection. Profile context files: When a profile includes context = "CONTEXT.md" , the referenced markdown file is automatically appended to ~/SANDBOX_CONTEXT.md and tool-native auto-context files (e.g., ~/.claude/CLAUDE.md ) under a # U