> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Toolbox Images

> Build, customize, and manage sandbox images using templates, runtimes, packages, and AI coding tools.

## What is a Toolbox

A toolbox is a container image that provides the development stack: runtimes, package managers, IDEs, and utilities. Application code is **not** baked into the image — developers clone and manage repos inside the running sandbox.

Every toolbox image includes the dev access layer:

| Component       | Purpose                                   |
| :-------------- | :---------------------------------------- |
| openssh-server  | SSH for VS Code Remote, JetBrains Gateway |
| code-server     | VS Code in browser (port 8443)            |
| ttyd            | Browser terminal (port 7681)              |
| Claude Code CLI | AI coding assistant                       |
| gh CLI          | GitHub operations                         |

## Build Modes

Build toolbox images from the **Images** page in the web UI.

### Scratch

Build an image interactively by selecting components:

| Step                | Description                                                      |
| :------------------ | :--------------------------------------------------------------- |
| Template (optional) | Start from a pre-built template for faster builds                |
| Runtimes            | Choose from 11 languages with version selection                  |
| System Packages     | Search/add from 7 categories or type custom apt package names    |
| Install Commands    | Shell commands run during build                                  |
| AI Coding Tools     | Claude Code, Codex CLI, Gemini CLI, Plandex, OpenCode, or custom |
| VS Code Extensions  | Extensions bundled into the image                                |

### BYOI (Bring Your Own Image)

Provide an existing OCI image reference. The dev access layer (SSH, code-server, ttyd, gateway) is layered on top automatically.

## Templates

Templates are pre-built toolbox images available as starting points. Selecting a template skips the base tool installation and only adds your customizations, making builds significantly faster.

| Template          | Description                       |
| :---------------- | :-------------------------------- |
| Blank             | Ubuntu 24.04 + SSH + Claude Code  |
| Python API        | Flask / FastAPI / Django          |
| Node.js Fullstack | React / Next.js / Express         |
| Go Microservice   | Go APIs / gRPC services           |
| Java API          | Spring Boot / Quarkus / Micronaut |
| Rust              | Systems / CLI tools / WebAssembly |
| Data Science      | pandas / ML workflows             |
| AI / Agents       | Claude Code / LangChain / RAG     |

## Supported Runtimes

| Runtime | Default Version | Install Method        |
| :------ | :-------------- | :-------------------- |
| Python  | 3.12            | Base image or apt     |
| Node.js | 20              | NodeSource apt repo   |
| Go      | 1.23            | Binary tarball        |
| Rust    | stable          | rustup                |
| Java    | 21              | Temurin JDK           |
| Ruby    | system          | apt                   |
| .NET    | 8.0             | apt                   |
| PHP     | system          | apt + Composer        |
| Elixir  | system          | apt (Erlang + Elixir) |
| Kotlin  | latest          | JetBrains release zip |
| Swift   | 5.9             | Swift.org tarball     |

## Image Forking

When a developer installs packages inside a running sandbox, those changes can be detected and captured into a new image via the **Fork** feature.

Fork detection compares the current state against snapshots taken at boot:

| Package Manager    | What's Detected              |
| :----------------- | :--------------------------- |
| apt                | New system packages          |
| pip                | New Python packages (global) |
| npm                | New Node packages (global)   |
| VS Code extensions | Newly installed extensions   |

Click **Fork** on a running sandbox to see detected changes and build a new image that includes them.

## Build Progress

When you start a build, a modal shows live progress:

1. **Creating** — preparing the build
2. **Building** — executing the Dockerfile (installing runtimes, packages, tools)
3. **Pushing** — uploading the image to the registry
4. **Done** — image available for use

Build logs stream in real time. If a build fails, the log shows which step failed and why.

## Managing Images

The **Images** page lists all toolbox images in your [org](/reference/org):

| Action      | Description                                   |
| :---------- | :-------------------------------------------- |
| Build       | Create a new image from scratch or a template |
| Clone       | Copy an existing image config to a new image  |
| Set Default | Set as the default image for new sandboxes    |
| Delete      | Remove the image from the registry            |