# Codebox 用户手册

Codebox 是**UCloud基于AstraFlow星图Sandbox 的云端开发盒子**。你只需提供一个 Git 仓库地址，Codebox 会在云端拉起一个预装 AI 编程助手的开发环境，并通过浏览器直接访问——无需本地安装、配置环境。

## 它能做什么

- **一键拉起环境**：从 Git 仓库创建开发沙箱，自动 clone 代码到 `/home/user/app`。
- **自带 AI 助手**：环境内预配 Claude Code、Codex、Jupyter-AI，开箱即用。
- **浏览器即用**：创建完成后拿到访问地址与密码，打开浏览器登录即可开始编码。
- **按需暂停/恢复**：闲置自动暂停，访问时自动恢复，节省资源。

## 两种场景

| 场景    | 类型              | 说明                                                         |
| ------- | ----------------- | ------------------------------------------------------------ |
| VSCode  | `codebox-vscode`  | 基于 code-server 的 Web 版 VSCode，适合通用编码与 AI 结对编程 |
| Jupyter | `codebox-jupyter` | 基于 JupyterLab 的数据科学环境，自带 jupyter-ai 面板         |

## 快速开始

页面顶部展示 CodeBox 总数、运行中数量和已暂停数量，下方以卡片形式展示每个实例



[![CodeBox 页面概览](https://cdnv2-cache.udelivrs.com/2026/07/526b01ee3fd2da6334cc553b2257eb6c_1784196104135.png)](https://cdnv2-cache.udelivrs.com/2026/07/526b01ee3fd2da6334cc553b2257eb6c_1784196104135.png)

- **运行中**：正在使用沙箱 vCPU 和内存资源，可以直接打开。
- **已暂停**：运行资源已冻结，不消耗沙箱 vCPU 和内存资源；需要使用时点击“启动”。
- **自动暂停**：运行中的实例闲置 1 小时后会自动暂停。

---



##  创建 Codebox
> 如果创建后暂时没有访问链接，通常表示环境仍在准备中，请稍后刷新页面。若配置失败，实例可能被自动清理；请检查仓库地址和 API Key 后重新创建


点击“创建CodeBox”后，按下面的说明填写表单。

[![创建 CodeBox 表单](https://cdnv2-cache.udelivrs.com/2026/07/d1a67a3e1cc0adb56bf7a883bca58a1f_1784196104129.png)](https://cdnv2-cache.udelivrs.com/2026/07/d1a67a3e1cc0adb56bf7a883bca58a1f_1784196104129.png)

| 字段 | 如何填写 |
| --- | --- |
| 名称 | 输入便于识别的名称，例如 `demo-vscode`。建议同时体现项目和环境。 |
| 环境 | 选择 `VS code` 或 `Jupyter`。 |
| Git仓库地址 | 输入 Codebox 需要拉取的 Git 仓库地址。 |
| 访问密码 | 设置登录开发环境时使用的密码，请妥善保管。 |
| API Key | 从下拉列表中选择已有密钥；没有可用密钥时点击“创建API key”。 |

填写完成后点击“创建”。系统会开始准备开发环境，包括拉取代码、配置 AI 助手和启动服务。此过程是异步的，创建窗口关闭并不代表环境已经可以使用，请以实例状态为准。




## 打开开发环境
> 访问链接和密码可用于进入你的开发环境，请不要发布到公开文档、群聊或代码仓库中

实例变为“运行中”后，可以在卡片中查看和管理它，也可以点击访问链接旁的复制按钮，再将链接粘贴到浏览器中打开。密码默认隐藏，可使用密码右侧的显示或复制按钮。

[![运行中实例的操作区域，实例信息为示例数据](https://cdnv2-cache.udelivrs.com/2026/07/6c0eec1186a21c639fa8dd1402683b34_1784196104132.png)](https://cdnv2-cache.udelivrs.com/2026/07/6c0eec1186a21c639fa8dd1402683b34_1784196104132.png)

1. 点击“打开”，进入 VS Code 或 Jupyter 登录页。
2. 输入创建时设置的访问密码。
3. 登录后，在 `/home/user/app` 目录中查看已拉取的仓库代码。





## 管理实例

### 暂停与启动

- 运行中的实例点击“暂停”后会冻结运行资源，代码和配置会保留。
- 已暂停的实例点击“启动”，等待状态恢复为“运行中”后再打开。
- 实例闲置 1 小时会自动暂停，需要继续使用时重新启动即可。

### 删除

点击“删除”可永久移除 CodeBox。删除前请确认重要代码已经提交并推送到远程仓库；删除操作不可恢复。

## 访问与使用

### 访问地址规则
> 地址以列表中展示的访问地址为准，沙箱内启动服务，可以通过相同的规则访问

地址格式：`{端口}-{SandboxID}.cn-wlcb.sandbox.ucloudai.com`

- VSCode：端口 `8080`，无后缀
  - 例：`8080-sbx-xxx.cn-wlcb.sandbox.ucloudai.com`
- Jupyter：端口 `8888`，后缀 `/lab`
  - 例：`8888-sbx-xxx.cn-wlcb.sandbox.ucloudai.com/lab`



## 限制与约束

- **地域**：当前仅支持 `cn-wlcb`（WCLB），不可切换。
- **密码长度**：最长 50 字符。
- **名称长度**：最长 50 字符。
- **类型**：仅支持 VSCode 与 Jupyter 两种。
- **必填字段**：创建时名称、Git 仓库地址、类型、APIKey、登录密码均不可为空。
- **异步语义**：提交创建成功不代表环境立即可用，必须以状态变为 `running` 为准。

---

## 常见问题

**Q：创建成功后访问地址为空？**
A：实例仍处于 `preparing`。请在列表中等待状态变为 `running`，访问地址会随后展示。

**Q：状态显示 running，但打开地址打不开？**
A：服务可能尚未完全就绪，**主要受限于Git Clone 仓库的速率**。系统会自动把这类情况校正为 `preparing`，请稍候再次查看。若长时间不恢复，建议删除后重新创建。

**Q：AI 助手没有反应？**
A：AI 配置在后台异步写入。请确认状态已是 `running`，并检查创建时填写的 APIKey 是否有效。

**Q：暂停后数据会丢失吗？**
A：不会。暂停仅回收运行资源，代码与配置保留；再次访问会自动恢复。

**Q：创建后列表里看不到？**
A：可能是后台配置失败导致沙箱被自动销毁。请检查 Git 仓库地址是否可访问、APIKey 是否有效，然后重新创建。