mhommen/OpenCode-Docker-Sandbox

# OpenCode Docker 沙盒 在使用本地或远程 Ollama 服务器的同时，在经过强化的 Docker 容器内运行 OpenCode AI 编程 CLI。 本项目专为那些希望在本地试验编程 AI Agent，同时又不想让它们直接访问宿主机的开发者而设计。 ## 为什么会有这个项目 AI 编程 Agent 非常实用，但它们也能执行命令、编辑文件、安装工具，并且极快地犯错。 直接在宿主机上运行 Agent 可能会让人感到不安，尤其是在测试新模型、工具或工作流时。 这个沙盒提供了一个实用的折中方案： * OpenCode 运行在 Docker 容器内 * 仅挂载选定的项目目录 * 使用宿主机的 UID/GID 写入文件 * Ollama 仍然运行在宿主机或其他可访问的机器上 * 容器以非 root 用户身份运行 * 移除了 `sudo`、`su` 和 `pkexec` 等权限提升工具 * 启动器会丢弃 Linux capabilities 它并非完美的安全边界，但能有效降低本地 Agent 试验的爆炸半径。 ## 包含的内容 该镜像目前包含： * Ubuntu 26.04 基础镜像 * Node.js 22 * .NET 9 SDK 和运行时 * Python 3 * 常用的构建工具 * 默认编辑器 Neovim * 通过 `opencode-ai` npm 包提供的 OpenCode CLI * 支持 Ollama CLI 容器内不会启动 Ollama 服务器。容器将连接到运行在宿主机或其他可访问机器上的 Ollama 服务器。 ## 前置要求 你需要： * Docker * 容器可访问的 Ollama 服务器 * 在 Ollama 中至少拉取一个模型 * 一个你想要处理的项目目录 示例： ``` ollama pull ``` ## 快速开始 克隆仓库： ``` git clone https://github.com/mhommen/OpenCode-Docker-Sandbox.git cd OpenCode-Docker-Sandbox ``` 构建镜像： ``` ./build-image.sh ``` 在项目目录中启动 OpenCode： ``` ./ocsb.sh ~/projects/my-app ``` 项目目录将被挂载到容器内的： ``` /source ``` OpenCode 将在该目录中启动。 ## 使用远程 Ollama 服务器 默认情况下，启动器使用： ``` http://host.docker.internal:11434 ``` 你可以使用 `-o` 或 `--ollama` 覆盖它： ``` ./ocsb.sh -o http://192.168.1.10:11434 ~/projects/my-app ``` 当 Ollama 运行在本地网络中的另一台机器上时，这非常有用。 ## 工作原理 启动脚本会： 1. 检查项目目录 2. 将其作为 `/source` 挂载到容器中 3. 创建临时的 OpenCode 配置 4. 将 OpenCode 指向兼容 OpenAI API 的 Ollama 接口 5. 以非 root 用户身份启动容器 6. 丢弃容器的 capabilities 7. 在挂载的项目中启动 OpenCode 随后，entrypoint 会向 Ollama 查询可用模型，并将检测到的第一个模型作为默认的 OpenCode 模型。 ## 安全模型 此沙盒旨在降低试验本地 AI 编程 Agent 时的风险。 它通过以下方式实现： * 以非 root 用户 `developer` 身份运行 * 匹配宿主机的 UID/GID，避免在宿主机上产生 root 所属的文件 * 仅挂载选定的项目目录 * 移除 `sudo`、`su`、`sudoedit`、`sudoreplay` 和 `pkexec` * 通过启动器丢弃 Linux capabilities * 将 Ollama 服务器保留在容器外部 * 避免直接访问你的整个主目录 ## 重要限制 这并不是一个针对恶意代码的强隔离边界。 Docker 容器是有用的隔离层，但它们并不是虚拟机。坚定的攻击者、恶意的依赖项或容器逃逸漏洞仍然可能带来危险。 请将此项目作为本地试验的实用安全层，而不是将其视为不受信任代码无害的绝对保证。 特别是： * 挂载的项目目录可能会被 Agent 修改 * 容器内仍然可以使用网络访问 * 命令仍然可以在容器内运行 * 挂载项目中的密钥可能会对 Agent 可见 * 必须信任 Docker 本身 如需更强的隔离，请考虑使用虚拟机（VM）、微型虚拟机（microVM）、一次性开发环境或专用机器。 ## 仓库布局 | 路径 | 用途 | | -------------------------- | ----------------------------------------------------- | | `Dockerfile` | 定义沙盒镜像 | | `build-image.sh` | 使用你宿主机的 UID/GID 构建镜像 | | `ocsb.sh` | 为选定的项目目录启动容器 | | `scripts/oc-entrypoint.sh` | 发现 Ollama 模型并启动 OpenCode | ## 自定义镜像名称或标签 辅助脚本通过环境变量支持自定义镜像名称和标签。 示例： ``` IMAGE_NAME=opencode-sandbox IMAGE_TAG=test ./build-image.sh ``` 使用相同的值运行它： ``` IMAGE_NAME=opencode-sandbox IMAGE_TAG=test ./ocsb.sh ~/projects/my-app ``` ## 故障排除 ### OpenCode 启动了，但未找到 Ollama 模型 确保 Ollama 正在运行： ``` ollama list ``` 检查 Ollama API 是否可访问： ``` curl http://localhost:11434/api/tags ``` 使用远程 Ollama 服务器时，请显式传入 URL： ``` ./ocsb.sh -o http://192.168.1.10:11434 ~/projects/my-app ``` ### 文件归属于错误的用户 在你要使用它的机器和用户账户上重新构建镜像： ``` ./build-image.sh ``` 镜像在构建过程中会固化你当前的 UID/GID。 ### Agent 无法访问项目外部的文件 这是有意为之的。 只有选定的项目目录会被挂载到 `/source`。如果你想公开不同的项目，请使用不同的目录启动沙盒。 ## 建议的用例 本项目适用于： * 尝试将 OpenCode 与本地 Ollama 模型结合使用 * 比较本地编程模型 * 让 Agent 在临时分支上工作 * 在受限环境中试验生成的代码 * 避免 Agent 直接访问你的宿主系统 ## 不推荐用于 本项目不适用于： * 安全地运行恶意代码 * 处理高度敏感的密钥 * 隔离生产环境的凭据 * 替代正式的虚拟机或经过强化的沙盒 * 给予不受信任的 Agent 不受限的互联网访问权限 ## 许可证 MIT

标签：AI编程助手, AI风险缓解, Cutter, Docker沙箱, MITM代理, NIDS, 多人体追踪, 安全隔离, 容器化, 开发环境, 请求拦截, 逆向工具