# Codebox User Manual Codebox is **UCloud's cloud development box based on the AstraFlow Sandbox**. You only need to provide a Git repository address, and Codebox will start a development environment with an AI coding assistant preinstalled in the cloud, accessible directly from your browser — no local installation or environment configuration required. ## What It Can Do - **Start an environment in one click**: create a development sandbox from a Git repository, with the code automatically cloned to `/home/user/app`. - **Built-in AI assistants**: Claude Code, Codex, and Jupyter-AI are preconfigured in the environment and ready to use out of the box. - **Ready to use in the browser**: once creation completes, you get an access address and a password. Open your browser, log in, and start coding. - **Pause and resume on demand**: instances are paused automatically when idle and resumed automatically when accessed, saving resources. ## Two Scenarios | Scenario | Type | Description | | -------- | ----------------- | ------------------------------------------------------------------------------- | | VSCode | `codebox-vscode` | Web-based VSCode powered by code-server, suitable for general coding and AI pair programming | | Jupyter | `codebox-jupyter` | Data science environment powered by JupyterLab, with a built-in jupyter-ai panel | ## Quick Start The top of the page shows the total number of CodeBox instances, how many are running, and how many are paused. Each instance is displayed as a card below. [![CodeBox page overview](https://cdnv2-cache.udelivrs.com/2026/08/5c661d0e547be7d85f81a08f9ff2d6c4_1786071504831.png)](https://cdnv2-cache.udelivrs.com/2026/08/5c661d0e547be7d85f81a08f9ff2d6c4_1786071504831.png) - **Running**: the instance is using sandbox vCPU and memory resources and can be opened directly. - **Paused**: the running resources are frozen and no sandbox vCPU or memory resources are consumed. Click **Start** when you need to use it. - **Auto-pause**: a running instance is paused automatically after 1 hour of inactivity. --- ## Creating a Codebox > If no access link is available right after creation, the environment is usually still being prepared; refresh the page later. If configuration fails, the instance may be cleaned up automatically; check the repository address and API Key, then create it again. After clicking **Create CodeBox**, fill in the form as described below. [![Create CodeBox form](https://cdnv2-cache.udelivrs.com/2026/08/77365360522fb6310fc8fdafbd807e7b_1786071173955.png)](https://cdnv2-cache.udelivrs.com/2026/08/77365360522fb6310fc8fdafbd807e7b_1786071173955.png) | Field | How to fill it in | | --- | --- | | Name | Enter a recognizable name, for example `demo-vscode`. We recommend reflecting both the project and the environment. | | Environment | Select `VS code` or `Jupyter`. | | Git repository address | Enter the address of the Git repository that Codebox should pull. | | Access password | Set the password used to log in to the development environment, and keep it safe. | | API Key | Select an existing key from the drop-down list. If no key is available, click **Create API Key**. | After filling in the form, click **Create**. The system starts preparing the development environment, including pulling the code, configuring the AI assistant, and starting the services. This process is asynchronous — closing the creation window does not mean the environment is ready. The instance status is authoritative. ## Opening the Development Environment > The access link and password are used to enter your development environment. Do not publish them in public documents, group chats, or code repositories. Once the instance becomes **Running**, you can view and manage it on its card. You can also click the copy button next to the access link and paste the link into your browser. The password is hidden by default; use the show or copy button to the right of the password. [![Action area of a running instance; the instance information is sample data](https://cdnv2-cache.udelivrs.com/2026/08/bbbcc8e2995cbf737a7b9f9318e2a923_1786071173957.png)](https://cdnv2-cache.udelivrs.com/2026/08/bbbcc8e2995cbf737a7b9f9318e2a923_1786071173957.png) 1. Click **Open** to go to the VS Code or Jupyter login page. 2. Enter the access password you set at creation time. 3. After logging in, view the pulled repository code in the `/home/user/app` directory. ## Managing Instances ### Pause and Start - Clicking **Pause** on a running instance freezes its running resources; the code and configuration are retained. - Click **Start** on a paused instance, and wait until the status returns to **Running** before opening it. - An instance is paused automatically after 1 hour of inactivity; simply start it again when you want to continue using it. ### Delete Click **Delete** to permanently remove the CodeBox. Before deleting, make sure important code has been committed and pushed to the remote repository. Deletion cannot be undone. ## Access and Usage ### Access Address Rules > The access address shown in the list is authoritative. Services started inside the sandbox can be accessed using the same rules. Address format: `{port}-{SandboxID}.cn-wlcb.sandbox.ucloudai.com` - VSCode: port `8080`, no suffix - Example: `8080-sbx-xxx.cn-wlcb.sandbox.ucloudai.com` - Jupyter: port `8888`, suffix `/lab` - Example: `8888-sbx-xxx.cn-wlcb.sandbox.ucloudai.com/lab` ## Limits and Constraints - **Region**: currently only `cn-wlcb` is supported and cannot be changed. - **Password length**: up to 50 characters. - **Name length**: up to 50 characters. - **Types**: only VSCode and Jupyter are supported. - **Required fields**: at creation time, the name, Git repository address, type, API Key, and login password must all be non-empty. - **Asynchronous semantics**: a successful creation request does not mean the environment is immediately available. The status becoming `running` is authoritative. --- ## FAQ **Q: The access address is empty after creation succeeds.** A: The instance is still in `preparing`. Wait in the list until the status becomes `running`, and the access address will be displayed afterwards. **Q: The status shows running, but the address does not open.** A: The service may not be fully ready yet — this is **mainly limited by the speed of cloning the Git repository**. The system automatically corrects such cases back to `preparing`; check again in a moment. If it does not recover for a long time, we recommend deleting the instance and creating it again. **Q: The AI assistant does not respond.** A: The AI configuration is written asynchronously in the background. Make sure the status is already `running`, and check whether the API Key you entered at creation time is valid. **Q: Will data be lost after pausing?** A: No. Pausing only reclaims running resources; the code and configuration are retained, and the environment is resumed automatically on the next access. **Q: I cannot see the instance in the list after creating it.** A: The sandbox may have been destroyed automatically because background configuration failed. Check whether the Git repository address is accessible and whether the API Key is valid, then create it again.