joakimwinum/pi-coding-agent-sandbox

# pi-coding-agent-sandbox 一个专为 GitHub Codespaces 定制的 Docker 沙箱，用于运行 [pi coding agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)，并通过 Squid 代理牢笼和 HTTPS 出站白名单进行限制。 此设置假定您正在通过 Codex Subscription 提供商 (`openai-codex`) 使用 ChatGPT Plus/Pro 订阅账户。它围绕以下身份验证流程设计：在主机上存储 pi/Codex 身份验证文件，然后将其复制到受限制的容器中。 ## 动机 目标是在一次性容器内运行 pi，以便代理能够在当前仓库上工作，而不会暴露主机文件系统的其余部分，同时将运行时的网络出站限制为 Codex Subscription 提供商所需的 LLM 提供商主机。 ## 它的作用 `pi-coding-agent-sandbox.sh` 创建两个 Docker 容器： - **Agent 容器**：安装了 Node.js、pi、Git、ripgrep、Python、Java 运行时、Go 和 Rust 工具链的 Ubuntu 24.04。 - **Squid 代理容器**：唯一拥有公共互联网出站权限的容器。 Agent 容器被放置在内部 Docker 网络中，只能访问 Squid 的 `3128` 端口。Squid 使用本地生成的 CA 执行 HTTPS 拦截，拒绝纯 HTTP/端口 `80`，明确拒绝格式错误/不支持的拦截流量而不是对其进行隧道传输，并且只允许流量发往： ``` chatgpt.com ``` `chatgpt.com` 仅涵盖确切的主机。除非子域名也应被允许，否则不要添加 `.chatgpt.com`。 所有其他的 Agent 出站流量，包括直接 DNS 查询和试图绕过代理变量的尝试，都会被 Docker 网络加上主机的 `nftables` 规则所拦截。 ## 预期环境 此脚本专为在 **GitHub Codespaces** 内运行而定制。 它期望一个具备以下条件的 Linux 环境： - Docker - 非以 root 用户运行时的 `sudo` - `nft` - `openssl` - 仅在首次进行 pi/Codex 身份验证时才需要的 `npm` ## 订阅/Codex 假设 此项目假定您当前的设置是： - ChatGPT Plus 或 Pro 订阅 - Codex Subscription 身份验证 - pi 提供商：`openai-codex` - 示例模型调用：`gpt-5.5` 脚本会在以下路径查找主机身份验证信息： ``` ~/.pi/agent/auth.json ``` 如果缺失，脚本会在主机上安装并运行一次 pi 以便您进行身份验证，然后将该身份验证文件复制到受限制的容器中。 ## 使用方法 从仓库根目录运行： ``` ./pi-coding-agent-sandbox.sh ``` 在设置和冒烟测试完成后，您将进入受限制的 Agent 容器内的一个 shell，同时当前仓库会被以读写模式挂载到 `/app`。 在 shell 内部运行 pi： ``` pi --provider openai-codex --model gpt-5.5 --thinking medium ``` 当您退出 shell 时，脚本将移除运行时容器、Docker 网络和 `nftables` 限制规则。 ## 生成的文件 运行时文件被写入以下目录： ``` ~/.pi-coding-agent-sandbox ``` 这包括生成的 Dockerfile、Squid 配置、白名单以及本地 Squid CA。 ## 有用的环境变量 您可以在运行脚本之前覆盖默认值，例如： ``` NODE_MAJOR=22 ./pi-coding-agent-sandbox.sh CLEAN_IMAGES=1 ./pi-coding-agent-sandbox.sh HOST_AUTH_JSON=/path/to/auth.json ./pi-coding-agent-sandbox.sh ALLOWED_DOMAINS="chatgpt.com" ./pi-coding-agent-sandbox.sh ``` 常用变量： - `HOST_AUTH_JSON` — 主机 pi 身份验证文件的路径；默认为 `~/.pi/agent/auth.json` - `NODE_MAJOR` — Agent 镜像的 Node.js 主版本号；默认为 `22` - `ALLOWED_DOMAINS` — 以逗号、空格或换行符分隔的 Squid 白名单；默认为 `chatgpt.com` - `CLEAN_IMAGES=1` — 在启动清理期间移除之前构建的沙箱镜像 - `WORKDIR` — 生成的运行时/配置目录；默认为 `~/.pi-coding-agent-sandbox` ## 安全模型与局限性 - 当前仓库被有意以读写模式挂载到 `/app`；沙箱旨在保护该挂载点之外的主机文件。 - Agent 容器的运行时出站流量被强制通过 Squid，并限制为配置的 HTTPS 白名单，同时拒绝纯 HTTP/端口 `80`。 - Squid 容器是受信任的出站策略组件，拥有公共互联网访问权限，以便代理白名单中的请求。 - 镜像构建和任何首次主机身份验证发生在运行时限制生效之前，可能需要更广泛的网络访问。 - 默认的 HTTPS 白名单故意设置得很小，仅包含确切的主机 `chatgpt.com`。 - 脚本会将您的 pi/Codex 身份验证文件复制到运行时容器中。 - 该脚本针对 Codespaces 进行了优化，可能需要针对其他主机或 Docker 设置进行调整。 - Squid 使用安装到 Agent 镜像中的本地生成的 CA 执行 TLS 拦截。 - 这是一个实用的隔离设置，而不是正式的安全边界或经过审计的沙箱。 ## 许可证 MIT

标签：AI编程助手, Cutter, DevSecOps, Docker, GitHub Codespaces, GNU通用公共许可证, HTTPS拦截, HTTPS白名单, MITM代理, nftables, Node.js, Squid Proxy, Web截图, Zero Trust, 上游代理, 代理拦截, 代码审计沙箱, 出口过滤, 大模型安全, 子域名枚举, 安全测试工具, 安全防御评估, 安全防护, 容器安全, 微隔离, 恶意代码分析, 沙箱, 系统安全, 网络安全, 网络隔离, 请求拦截, 配置文件, 隐私保护