企业官网建设流程全解析

CloudCLI 沙箱化部署指南：用 Docker Sandbox 在任意浏览器与移动端运行 Claude Code 与 Codex

【免费下载链接】claudecodeuiUse Claude Code, OpenCode, Cursor CLI, and Codex on mobile and web with CloudCLI (aka Claude Code UI). CloudCLI is a free open source webui/GUI that helps you manage your Claude Code session and projects remotely.项目地址: https://gitcode.com/GitHub_Trending/cl/claudecodeui

CloudCLI（即 Claude Code UI）的 Docker Sandbox 模板，让 Claude Code、OpenAI Codex 等 AI 编码 Agent 运行在隔离的轻量级 microVM 中，并通过一个 Web/Mobile IDE 从任意浏览器、任意设备访问。本文基于仓库中的 docker/README.md 展开，结合 docker/claude-code/Dockerfile、docker/codex/Dockerfile、server/modules/cli/sandbox.service.ts 等源码，完整讲解环境安装、凭据管理、沙箱创建与生命周期管理、环境变量配置、网络策略以及高级用法，读完即可从零拉起一个带完整 IDE 的沙箱化编码环境。

为什么需要沙箱化的 Web/Mobile IDE

本地运行 Claude Code 时，CLI 进程直接暴露在你的主机上，依赖本机 Node 环境、全局包状态与 API 凭据。而 Docker Sandbox 的思路是：把 Agent 运行在 Docker 管理的隔离 microVM 中，主机只保留一个轻量的sbx命令行工具，API Key 由sbx统一保管，凭据本身不进入沙箱。

这种模式的直接收益：

• 隔离：Agent 产生的文件操作、进程、网络请求都被限制在沙箱内，~/my-project之外的主机目录不受影响；
• 跨设备访问：沙箱内自动启动 CloudCLI 服务端，浏览器、平板、手机均可访问同一个编码环境；
• 环境一致：镜像内预装 Node.js、构建工具与 CloudCLI，团队共享同一套模板镜像（docker.io/cloudcliai/sandbox:claude-code/:codex），避免"在我机器上能跑"的问题。

仓库中的模板正是为此而设计：两个 Dockerfile 分别基于docker/sandbox-templates:claude-code与docker/sandbox-templates:codex基础镜像，叠加 CloudCLI 与自动启动逻辑。

第一步：安装 sbx CLI

Docker Sandboxes 将 Agent 运行在隔离的 microVM 中，sbx是唯一需要在宿主机安装的组件。官方提供的三种安装方式（完整步骤见 Docker 官方 Sandboxes 文档）：

• macOS：brew install docker/tap/sbx
• Windows：winget install -h Docker.sbx
• Linux：sudo apt-get install docker-sbx

注意：sbx是宿主机工具，沙箱内并不需要安装它；沙箱内部只有 CloudCLI 与对应 Agent（Claude Code / Codex）。

第二步：存储 API Key

sandbox.service.ts中的映射关系表明，每个 Agent 对应一个sbx全局密钥名：

先登录并存储一次：

sbx login sbx secret set -g anthropic

sbx负责安全地管理凭据，API Key 不会进入沙箱，Agent 在沙箱内部通过sbx注入的凭据运行。从 sandbox.service.ts 可以看到，cloudcli sandbox在创建前会先执行sbx secret ls检查对应密钥是否存在（SANDBOX_SECRETS = { claude: 'anthropic', codex: 'openai' }），缺失时会明确提示先执行sbx secret set -g <secret>。

第三步：一条命令启动 Claude Code

npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project

这条命令做的事情（对应 sandbox.service.ts 的create分支）：

1. 校验工作区路径~/my-project真实存在；
2. 派生沙箱名（默认取工作区目录名，如my-project），并校验其只包含字母、数字、连字符与下划线（正则/^[\w-]+$/）；
3. 检查sbxCLI 是否已安装、对应 API 密钥是否已存储；
4. 以后台方式执行sbx run --template docker.io/cloudcliai/sandbox:claude-code --name my-project claude ~/my-project；
5. 等待约 5 秒后，在沙箱内启动 CloudCLI 服务端：nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 & disown；
6. 执行sbx ports my-project --publish 3001:3001把沙箱内 3001 端口转发到宿主机（若端口被占用会自动尝试 3002）。

完成后，用浏览器打开http://localhost:3001。首次访问会要求设置密码，之后即可开始使用。

提示：npx方式会临时拉取包；如果希望后续直接使用cloudcli sandbox ...系列子命令，可全局安装：npm install -g @cloudcli-ai/cloudcli。

使用不同的 Agent：OpenAI Codex

切换到 Codex 只需存储对应密钥并传入--agent：

sbx secret set -g openai npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --agent codex

cloudcli sandbox支持的 Agent 参数（源码默认值）为claude（默认）与codex，并据此自动选择模板镜像与密钥名。--agent可简写为-a，例如cloudcli sandbox ~/my-project -a codex --port 8080。

官方模板与镜像构成

仓库docker/目录下维护两个模板目录，对应sbx可直接使用的两个镜像标签：

使用--template参数可以在sbx run时直接指定（见下文"高级用法"）。这两个标签在 sandbox.service.ts 中与 Agent 一一对应。

从镜像构建源码看模板的实际构成（claude-code Dockerfile 与 codex Dockerfile 完全同构）：

FROM docker/sandbox-templates:claude-code # 或 docker/sandbox-templates:codex USER root COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh USER agent RUN --mount=type=cache,target=/tmp/npm-cache,sharing=locked,mode=0777 \ npm install -g @cloudcli-ai/cloudcli \ --cache=/tmp/npm-cache \ --fetch-retries=5 \ --fetch-retry-mintimeout=20000 \ --fetch-retry-maxtimeout=120000 \ --fetch-timeout=600000 \ --no-audit --no-fund && \ cloudcli --version COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

镜像构建的几个关键设计：

• 基础镜像：分别继承docker/sandbox-templates:claude-code与docker/sandbox-templates:codex，Node.js 由基础镜像提供；
• 原生模块编译依赖：install-cloudcli.sh 以 root 身份安装build-essential python3 python3-setuptools jq ripgrep sqlite3 zip unzip tree vim-tiny，注释明确说明这是为node-pty、better-sqlite3、bcrypt等原生模块准备的（与 package.json 中的依赖一致）；
• 全局安装：以agent用户执行npm install -g @cloudcli-ai/cloudcli，并通过 BuildKit 挂载缓存目录与重试参数，加快构建、提高网络不稳时的成功率，安装后立即cloudcli --version验证；
• 自动启动：start-cloudcli.sh被复制为/home/agent/.cloudcli-start.sh并写入.bashrc——这正是 README 所说"CloudCLI 通过.bashrc自动启动"的实现所在。

start-cloudcli.sh的启动逻辑（docker/shared/start-cloudcli.sh）：

if ! pgrep -f "server/index.js" > /dev/null 2>&1; then nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 & disown echo " CloudCLI is starting on port 3001..." echo " Forward the port from another terminal:" echo " sbx ports <sandbox-name> --publish 3001:3001" echo " Then open: http://localhost:3001" fi

它会检测server/index.js（CloudCLI 服务端进程标识）是否已在运行，未运行则后台拉起并提示端口转发方式。日志统一写入/tmp/cloudcli-ui.log，这也是cloudcli sandbox logs读取日志的来源。

管理沙箱：生命周期命令

使用原生 sbx 命令

sbx ls # 列出所有沙箱 sbx stop my-project # 停止（保留状态） sbx start my-project # 重启已停止的沙箱 sbx rm my-project # 彻底移除（含数据） sbx exec my-project bash # 在沙箱内打开 shell

其中sbx stop只是暂停沙箱（状态保留），sbx rm才会删除全部内容，两者语义不同，删除前请确认。

使用 cloudcli 子命令

如果已全局安装 CloudCLI（npm install -g @cloudcli-ai/cloudcli），还可以用更贴近业务语义的子命令：

cloudcli sandbox ls # 列出沙箱 cloudcli sandbox start my-project # 重启沙箱并重新拉起 Web UI cloudcli sandbox logs my-project # 查看服务端日志（读取 /tmp/cloudcli-ui.log）

这些子命令由 cli.service.ts 分发到 sandbox 服务，支持的子命令完整集合为ls / start / stop / rm / logs / help（cloudcli sandbox <路径>无子命令时默认执行"创建并启动"）。cloudcli sandbox start的实现流程是：sbx run my-project恢复沙箱 → 等待 5 秒 → 在沙箱内后台执行cloudcli start --port 3001→ 端口转发并输出访问地址。名字参数只接受\w-字符集，其余会被拒绝。

开箱即用的功能

沙箱内的 CloudCLI 是一个完整的 Web/Mobile IDE，README 列出的能力与 src/ 前端模块一一对应：

• Chat— Markdown 渲染、代码块、消息历史（对应 src/modules/chat）
• Files— 文件树与语法高亮编辑器（对应 src/modules/file-tree 与 src/modules/code-editor）
• Git— Diff 查看器、暂存、分支切换、提交（对应 src/modules/git-panel）
• Shell— 内置终端模拟器（对应 src/modules/shell，基于node-pty+ xterm）
• MCP— 可视化配置 Model Context Protocol 服务器（对应 src/modules/mcp）
• Mobile— 平板与手机浏览器均可使用（响应式布局）

项目目录采用双向挂载，沙箱内外的文件编辑会实时互相同步（README 原文："Your project directory is mounted bidirectionally — edits propagate in real time, both ways."）。因此你可以在本机 IDE 与沙箱 Web IDE 之间无缝切换编辑。

配置：环境变量与持久化

CloudCLI 服务端支持三个核心环境变量，README 参数表如下：

这些默认值在源码中都能找到印证：server/index.ts 读取SERVER_PORT（缺省 3001）与HOST（缺省0.0.0.0）；server/load-env.ts 在未显式设置DATABASE_PATH时将其固定为~/.cloudcli/auth.db，确保重新构建 dist-server 不会改变数据库存放位置。此外 cli.service.ts 还列出PORT（遗留别名）、CLAUDE_CLI_PATH（自定义 Claude CLI 路径）、CONTEXT_WINDOW（上下文窗口大小，默认 160000）等环境变量。

创建时注入

使用--env（可简写-e，且可重复）在创建沙箱时设置：

npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --env SERVER_PORT=8080

从 sandbox.service.ts 看，--env参数会先经/^\w+=.+$/正则校验（不合法的一律跳过并警告），合法的变量被拼成export KEY=VALUE追加写入沙箱内的/etc/sandbox-persistent.sh——这是 Docker Sandbox 的持久化环境文件，沙箱重启后依然生效。

运行时追加

对已在运行的沙箱，用sbx exec直接写入持久化文件：

sbx exec my-project bash -c 'echo "export SERVER_PORT=8080" >> /etc/sandbox-persistent.sh'

重启 CloudCLI 使配置生效

环境变量需要重启 CloudCLI 服务进程才能生效：

sbx exec my-project bash -c 'pkill -f "server/index.js"' sbx exec -d my-project cloudcli start --port 3001

pkill -f "server/index.js"与自动启动脚本的进程检测逻辑（pgrep -f "server/index.js"）保持一致，确保杀掉的是服务端进程而非其他进程。

高级用法：分支模式、多工作区、直传提示词

cloudcli sandbox面向最常见的"一键启动 Web UI"场景；若需要终端 Agent 体验、分支模式、多工作区、内存限制等能力，应直接使用sbx run+ 模板镜像：

# 终端 Agent + Web UI sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --name my-project sbx ports my-project --publish 3001:3001 # 分支模式（Git worktree 隔离） sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature # 多个工作区（:ro 表示只读挂载） sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/shared-libs:ro # 直接传递提示词 sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project -- "Fix the auth bug"

几个要点：

• 使用sbx run时，CloudCLI 会通过.bashrc里的start-cloudcli.sh自动启动（见上文镜像剖析），因此不需要额外命令即可获得 Web UI；
• --branch利用 Git worktree 实现分支级隔离，同一项目可在互不干扰的多个沙箱中并行开发；
• ~/shared-libs:ro语法支持多个工作区挂载，:ro后缀表示只读；
• 最后一个位置参数"Fix the auth bug"会直接作为提示词传给 Agent，适合 CI 或脚本化调用；
• 内存限制等其余选项见 Docker Sandboxes usage 文档。

网络策略：访问宿主机服务

沙箱默认限制出站访问。如果沙箱内的 Agent 需要访问宿主机上的服务（如本地运行的 Ollama 11434 端口），需显式放行：

sbx policy allow network localhost:11434 # 沙箱内部访问方式：curl http://host.docker.internal:11434

Web UI 本身不需要网络策略——通过sbx ports转发即可访问，无需放行规则。

源码视角：cloudcli sandbox 的关键实现细节

如果想要更深入了解这套机制，server/modules/cli/sandbox.service.ts 是核心实现文件，值得注意的细节：

• 模板与密钥映射：SANDBOX_TEMPLATES与SANDBOX_SECRETS两张表是--agent→ 镜像 / 密钥名映射的唯一事实来源（claude →claude-code模板 +anthropic密钥；codex →codex模板 +openai密钥）；
• 默认端口与自动端口回退：parseSandboxArguments中默认宿主端口 3001；publishSandboxPort执行sbx ports <name> --publish <port>:3001，若报address already in use会自动尝试port+1，两个端口都被占用才报错提示用--port指定；
• 启动时序：创建/启动沙箱后统一等待 5 秒再注入环境变量、拉起服务端并转发端口，避免竞态；
• 内部使用cloudcli start --port 3001：无论宿主端口如何，沙箱内部始终监听 3001，宿主端口仅由sbx ports转发决定；
• 对应单元测试见 server/modules/cli/tests/sandbox.service.test.ts，CLI 整体的参数解析与命令分发见 server/modules/cli/tests/cli.service.test.ts。

许可

本仓库（含 docker 模板）采用AGPL-3.0-or-later许可，使用时请注意其传染性条款与商业使用边界。

小结

本文完整梳理了 CloudCLI Docker Sandbox 模板的部署路径：安装sbx→ 存储 API Key →npx @cloudcli-ai/cloudcli sandbox <目录>一键启动，再到沙箱生命周期管理、环境变量注入与网络策略配置。通过 docker/claude-code/Dockerfile 与 docker/codex/Dockerfile 可以看到模板镜像的完整构成（构建工具、CloudCLI 全局安装、.bashrc自动启动），通过 server/modules/cli/sandbox.service.ts 可以理解cloudcli sandbox每个子命令背后的精确执行序列。无论是想在浏览器里远程编码、在手机上查看会话，还是用分支模式并行开发，这套模板都提供了开箱即用的隔离环境。

【免费下载链接】claudecodeuiUse Claude Code, OpenCode, Cursor CLI, and Codex on mobile and web with CloudCLI (aka Claude Code UI). CloudCLI is a free open source webui/GUI that helps you manage your Claude Code session and projects remotely.项目地址: https://gitcode.com/GitHub_Trending/cl/claudecodeui