code-on-incus (coi)

code-on-incus (coi) is a secure container runtime for AI coding tools built on Incus system containers. It runs AI coding assistants like Claude Code and opencode in isolated environments, protecting host SSH keys, environment variables, Git credentials, and other sensitive resources from exposure.

Core Capabilities#

Container Isolation & Security#

• System-level isolation via Incus (LXD fork), superior to Docker application containers
• Automatic UID mapping: No chown required, file permissions automatically mapped correctly
• Credential isolation: Host environment variables, SSH keys, Git credentials not exposed to AI tools by default
• Network security modes: Restricted (block private networks), Allowlist (whitelist), Open (unlimited)
• Protected paths: .git/hooks, .git/config, .husky, .vscode mounted read-only by default

Real-time Security Monitoring#

• Threat detection: Reverse shells, data exfiltration, environment scanning, suspicious port connections
• NFT network monitoring: Kernel-level real-time network traffic detection (nftables)
• Auto-response: Four levels (INFO/WARNING/HIGH/CRITICAL), supports automatic container pause or kill
• Audit logs: JSON Lines format stored in ~/.coi/audit/

Session Management#

• Multi-slot support: Run multiple isolated sessions in the same workspace in parallel
• Session recovery: --resume restores complete conversation history and credentials
• Persistent mode: --persistent retains containers and installed packages
• Snapshot management: coi snapshot create/restore/delete for complete state checkpoints

Resource Control#

• CPU limits: Core count, usage rate, priority
• Memory limits: Memory cap, swap control
• Disk I/O: Read/write rate limits
• Runtime duration: Auto-stop with graceful or forced shutdown

Use Cases#

• AI coding sandbox: Safely run Claude Code, opencode, and other AI coding assistants
• Sensitive project development: Prevent AI tools from accessing host sensitive credentials
• Parallel development sessions: Multi-slot support for multiple independent coding sessions
• Code review & experimentation: Create checkpoints, rollbacks, and branch experiments via snapshots
• macOS development environment: Get Linux-like container isolation via Colima/Lima

Installation & Quick Start#

# Auto installation
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

# Manual installation (Linux AMD64)
wget https://github.com/mensfeld/code-on-incus/releases/download/v0.6.0/coi-linux-amd64
chmod +x coi-linux-amd64
sudo mv coi-linux-amd64 /usr/local/bin/coi

# Build image (first time, ~5-10 minutes)
coi build

# Enter project directory and start
cd your-project
coi shell

# Use opencode tool
coi shell --tool opencode

Prerequisites#

• Incus: Linux container manager
• incus-admin group: User must belong to this group
• Go 1.24.4+ (only needed for source compilation)

Core Commands#

coi shell                      # Interactive session (default Claude Code)
coi shell --persistent         # Persistent mode
coi shell --slot 2             # Use specified slot
coi shell --resume             # Resume last session
coi shell --network=allowlist  # Allowlist network mode
coi shell --limit-cpu=2 --limit-memory=2GiB --limit-duration=2h  # Resource limits
coi list --all                 # List containers and saved sessions
coi attach                     # Attach to running container
coi shutdown <name>            # Graceful shutdown
coi kill <name>                # Force terminate
coi clean                      # Clean up resources
coi snapshot create checkpoint-1   # Create snapshot
coi snapshot restore checkpoint-1  # Restore snapshot
coi monitor coi-abc-1 --watch 2    # Real-time security monitoring
coi health                          # System health check

Configuration File Example#

Configuration path: ~/.config/coi/config.toml

[defaults]
image = "coi"
persistent = true
mount_claude_config = true

[tool]
name = "claude"  # or "opencode"

[monitoring]
enabled = true
auto_pause_on_high = true
auto_kill_on_critical = true

[security]
additional_protected_paths = [".idea", "Makefile"]

Tech Stack#

Image Contents (coi base image)#

• Ubuntu 22.04
• Docker (full Docker-in-container support)
• Node.js 20 + npm
• Claude Code CLI
• GitHub CLI (gh)
• tmux
• Common build tools

Supported AI Coding Tools#

• Claude Code ✅
• opencode ✅
• Aider, Cursor, and others (marked as "Coming soon")

Architecture Support#

• x86_64/amd64 ✅
• aarch64/arm64 ✅

Information Pending Confirmation#

• Windows/WSL2 support details: README mentions WSL2, but documentation focuses on Linux and macOS, specific implementation to be confirmed
• Aider, Cursor support timeline: Marked as "Coming soon" with no specific date
• Independent website/documentation site: Not found, documentation集中在 GitHub README and Wiki