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.

{
  "memory_mb": 2048  // 2 GB
}

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:

{
  "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