code-on-incus：为 AI 编码代理提供独立隔离沙箱

code-on-incus（COI）是一款面向 AI 编码代理的开源隔离运行环境。它基于 Incus 容器管理器，为每一个 AI 代理分配一台独立的「虚拟机式」系统容器，拥有 root 权限、systemd 和 Docker，但与用户宿主机完全隔离，使代理可以像在真实服务器上一样安装软件、运行服务、管理包，而不会影响实际系统。

核心设计：凭据与威胁隔离

COI 的安全策略围绕「凭据不外泄、威胁自动处置」展开。SSH 密钥、环境变量、Git token 等敏感信息默认保留在宿主机上，只有用户显式挂载时才会进入容器。内核级 nftables 监控可实时检测反弹 shell、C2 连接、数据外传、DNS 隧道、凭据扫描等行为，并在判定为 HIGH 级别威胁时自动暂停容器、CRITICAL 时直接终止，无需人工介入。

工具还内置了多重防护检查：coi health 会验证 seccomp、AppArmor 和特权设置是否到位；当检测到 security.privileged=true 等破坏隔离的配置时会拒绝启动；对内核版本低于 5.15 的宿主机也会发出警告。

支持的 AI 编码工具

目前 COI 已适配三款主流 AI 编码代理：

Claude Code（默认）—— Anthropic 官方 CLI 工具
opencode —— 开源 AI 编码代理（opencode.ai）
pi —— AI 编码助手（pi.dev）

Aider 和 Cursor 在官方路线图中。工具切换通过 ~/.coi/config.toml 中的 [tool] 配置实现，并支持 bypass（默认，自主执行）与 interactive（逐项确认）两种权限模式。

关键功能特性

COI 的能力可分为三类：

会话与并行

多 slot 并行：同一工作区下可同时运行多个完全隔离的代理会话
会话恢复：支持断点续接，历史与凭据按工作区范围恢复
持久容器：容器可在会话间保留，已安装的工具不会丢失；即使在临时模式下，工作区文件也会持久化

宿主集成

SSH 代理转发：在容器内使用 Git-over-SSH 而无需复制私钥
宿主 socket 转发：将宿主 Unix socket 安全转发进容器，可用于凭据代理（生成短期 token，容器按需获取）
环境变量按名转发：可选地将指定 host 环境变量注入容器
时区继承：容器自动继承宿主时区
沙箱上下文文件：自动向 Claude Code、opencode、pi 注入 SANDBOX_CONTEXT.md，告知代理当前网络模式、工作区路径与持久化设置

安全机制

受保护路径：.git/hooks、.git/config 等敏感路径默认不可被代理修改
快照管理：可对容器创建检查点、回滚变更或分叉实验

容器方案选择：为何用 Incus 而非 Docker

COI 选择 Incus 而非 Docker 或 Docker Sandbox，主要原因是 Incus 提供「系统容器」——具备完整 init、systemd、可运行 Docker-in-Docker 的能力，同时支持快照和持久化状态，更接近一台真实的轻量虚拟机。Docker 沙箱在进程级隔离和系统服务支持上存在限制，难以满足代理对完整系统权限的需求。

快速上手

安装完成后，用户只需运行 coi shell 即可启动默认的 Claude Code 沙箱；通过 coi shell --profile opencode 可切换其他工具。配置文件支持全局（~/.coi/config.toml）与项目级（./coi/config.toml）两级覆盖。详细安装步骤、macOS 支持情况、故障排查等可在项目文档中查阅。