> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# Images

An **image** is a reference to a Docker image stored in Modbox. When you provision a sandbox, you specify which image to use. Images can be global defaults (available to all workspaces) or workspace-specific (private to your team).

## Pre-built images

Modbox provides a set of global default images:

| Image              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `modbox/code-exec` | Python, Node.js, Go, Bash — for code execution            |
| `modbox/chromium`  | Headless Chromium with CDP + VNC — for browser automation |
| `modbox/ubuntu`    | Bare Ubuntu 24.04 — for custom workloads                  |

These appear in your workspace automatically and cannot be deleted.

## Bring your own image

You can register any public or private Docker image:

```bash
POST /sandbox-images
X-Workspace-Id: your-workspace-id

{
  "name": "My Python Sandbox",
  "image": "ghcr.io/your-org/your-image",
  "tag": "latest",
  "description": "Custom Python environment with our libraries",
  "memory_mb": 1024,
  "ttl_seconds": 3600,
  "readiness_port": 8080
}
```

### Readiness probe

Modbox knows your sandbox is ready in two ways:

1. **HTTP probe** — set `readiness_port` and Modbox will poll `GET :{port}/` until it returns 2xx
2. **Process probe** — if `readiness_port` is not set, Modbox checks that `supervisord` is running via `pgrep supervisord`

Use the HTTP probe for web servers; use the process probe for general-purpose images.

### Memory limits

The `memory_mb` field sets the memory limit for containers using this image. Valid range: **256 MB – 8192 MB**.

```json
{
  "memory_mb": 2048  // 2 GB
}
```

## List images

```bash
GET /sandbox-images
GET /sandbox-images?enabled_only=true   # only enabled images
X-Workspace-Id: your-workspace-id       # includes workspace + global defaults
```

## Update an image

```bash
PUT /sandbox-images/{image_id}

{
  "tag": "v2.1.0",
  "memory_mb": 2048,
  "enabled": true
}
```

## Private registries

To use a private Docker image, first create a registry credential (see [Registries](/guides/registries)), then link it when creating the image:

```json
{
  "name": "Private App Image",
  "image": "registry.your-company.com/sandboxes/app",
  "tag": "main",
  "registry_id": "uuid-of-your-registry-credential"
}
```

Modbox will use the stored credentials to pull the image when provisioning sandboxes.

## Image fields

| Field            | Type    | Description                                           |
| ---------------- | ------- | ----------------------------------------------------- |
| `id`             | UUID    | Image ID — pass as `image_id` when provisioning       |
| `name`           | string  | Human-readable name                                   |
| `image`          | string  | Docker image path (e.g. `ghcr.io/org/image`)          |
| `tag`            | string  | Docker tag (default: `latest`)                        |
| `enabled`        | boolean | Only enabled images can be used for provisioning      |
| `is_default`     | boolean | Global default images are available to all workspaces |
| `memory_mb`      | integer | Memory limit in MB (256–8192)                         |
| `readiness_port` | integer | HTTP port for readiness probe (optional)              |
| `ttl_seconds`    | integer | Default TTL for sandboxes using this image (optional) |
| `workspace_id`   | UUID    | Workspace this image belongs to (`null` for global)   |
| `registry_id`    | UUID    | Registry credential for pulling (optional)            |