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:

These appear in your workspace automatically and cannot be deleted.

Bring your own image

You can register any public or private Docker image:

$
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.

1
{
2
  "memory_mb": 2048  // 2 GB
3
}

List images

$
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

$
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), then link it when creating the image:

1
{
2
  "name": "Private App Image",
3
  "image": "registry.your-company.com/sandboxes/app",
4
  "tag": "main",
5
  "registry_id": "uuid-of-your-registry-credential"
6
}

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

Image fields