code-on-incus

code-on-incus (coi) 是一个基于 Incus 系统容器的 AI 编码工具安全沙箱运行时。它通过系统级容器隔离，让 Claude Code、opencode 等 AI 编码助手在隔离环境中运行，保护宿主机的 SSH 密钥、环境变量、Git 凭据等敏感资源不被暴露。

核心能力#

容器隔离与安全#

• 基于 Incus（LXD 分支）提供系统级隔离，优于 Docker 应用容器
• 自动 UID 映射：无需 chown，文件权限自动正确映射
• 凭据隔离：宿主机环境变量、SSH 密钥、Git 凭据默认不暴露给 AI 工具
• 网络安全模式：Restricted（阻止私有网络）、Allowlist（白名单）、Open（无限制）
• 安全保护路径：.git/hooks、.git/config、.husky、.vscode 默认只读挂载

实时安全监控#

• 威胁检测：反向 Shell、数据窃取、环境扫描、可疑端口连接
• NFT 网络监控：内核级实时网络流量检测（nftables）
• 自动响应：INFO/WARNING/HIGH/CRITICAL 四级响应，支持自动暂停或杀死容器
• 审计日志：JSON Lines 格式存储于 ~/.coi/audit/

会话管理#

• 多槽位支持：同一工作区并行运行多个隔离会话
• 会话恢复：--resume 恢复完整对话历史和凭据
• 持久模式：--persistent 保留容器和已安装软件包
• 快照管理：coi snapshot create/restore/delete 完整状态检查点

资源控制#

• CPU 限制：核心数、使用率、优先级
• 内存限制：内存上限、swap 控制
• 磁盘 I/O：读写速率限制
• 运行时限：自动停止，支持优雅或强制关闭

适用场景#

• AI 编码沙箱：安全运行 Claude Code、opencode 等 AI 编码助手
• 敏感项目开发：防止 AI 工具访问宿主机敏感凭据
• 并行开发会话：多槽位同时运行多个独立编码会话
• 代码审查与实验：通过快照创建检查点、回滚、分支实验
• macOS 开发环境：通过 Colima/Lima 获得类似 Linux 容器隔离体验

安装与快速开始#

# 自动安装
curl -fsSL https://raw.githubusercontent.com/mensfeld/code-on-incus/master/install.sh | bash

# 手动安装（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

# 构建镜像（首次，约 5-10 分钟）
coi build

# 进入项目目录并启动
cd your-project
coi shell

# 使用 opencode 工具
coi shell --tool opencode

前置依赖#

• Incus：Linux 容器管理器
• incus-admin 组：用户必须属于此组
• Go 1.24.4+（仅源码编译需要）

核心命令#

coi shell                      # 交互式会话（默认 Claude Code）
coi shell --persistent         # 持久模式
coi shell --slot 2             # 使用指定槽位
coi shell --resume             # 恢复上次会话
coi shell --network=allowlist  # 白名单网络模式
coi shell --limit-cpu=2 --limit-memory=2GiB --limit-duration=2h  # 资源限制
coi list --all                 # 列出容器和保存的会话
coi attach                     # 附加到运行中的容器
coi shutdown <name>            # 优雅关闭
coi kill <name>                # 强制终止
coi clean                      # 清理资源
coi snapshot create checkpoint-1   # 创建快照
coi snapshot restore checkpoint-1  # 恢复快照
coi monitor coi-abc-1 --watch 2    # 实时安全监控
coi health                          # 系统健康检查

配置文件示例#

配置文件路径：~/.config/coi/config.toml

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

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

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

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

技术栈构成#

镜像内容（coi 基础镜像）#

• Ubuntu 22.04
• Docker（完整 Docker-in-container 支持）
• Node.js 20 + npm
• Claude Code CLI
• GitHub CLI (gh)
• tmux
• 常用构建工具

支持的 AI 编码工具#

• Claude Code ✅
• opencode ✅
• Aider、Cursor 等工具（官方标注 "Coming soon"）

架构支持#

• x86_64/amd64 ✅
• aarch64/arm64 ✅

待确认信息#

• Windows/WSL2 支持详情：README 提及 WSL2，但文档主要面向 Linux 和 macOS，具体实现待确认
• Aider、Cursor 等工具支持时间表：官方标注 "Coming soon"，无具体日期
• 是否有独立官网/文档站点：未发现，文档集中在 GitHub README 和 Wiki