Images - Documentation

Sandbox images allow you to create customized & reusable sandbox environments. They define the tools, languages, frameworks, and configurations that will be available when you spawn a new sandbox instance. Images are particularly useful for teams who need standardized environments or for creating many specialized sandboxes for repeated use cases (codegen agent, Git PR reviews agent, etc.).

What are sandbox images?

Sandbox images are pre-configured container images that serve as blueprints for creating sandboxes. Each image includes:

Base environment: Operating system and runtime configurations
Tools: Languages, frameworks, and development tools
Configuration: Environment variables, startup scripts, …
Resources: Memory allocated

When you create a sandbox from an image, Blaxel provisions a new instance with all the specifications defined in that image.

How sandbox images work

Initial setup: Follow this guide to create your sandbox image for the first time. Use bl push to push the image to Blaxel, or bl deploy to push the image and also create a sandbox from it.
Build phase: Your Dockerfile is used to create a container with all required tools and configurations.
Initialization phase: The sandbox API is injected and startup commands are executed.
Instantiation: New sandboxes can be spawned from this image in seconds.

You cannot directly use “library” container images (such as those hosted on Docker Hub and other registries) as sandbox images. Instead, you must create one or more custom images for your sandboxes using Dockerfiles and ensure that each image includes Blaxel’s sandbox API binary. This is necessary for sandbox functionality like process management and file operations.

Pre-built images

Blaxel provides a library of pre-built container images for common needs.

Image	Description
`blaxel/base-image:latest`	Minimal environment with Node.js 22 (Alpine) and Python 3.12
`blaxel/py-app:latest`	Python 3.12 development environment
`blaxel/ts-app:latest`	TypeScript development environment with Node.js 22 (slim)
`blaxel/node:latest`	Node.js development environment with Node.js 23 (Alpine)
`blaxel/nextjs:latest`	Next.js development environment with Node.js 22 (Alpine)
`blaxel/vite:latest`	Vite + React + TS development environment with Node.js 22 (Alpine)
`blaxel/astro:latest`	Astro development environment with Node.js 22 (Alpine)
`blaxel/expo:latest`	React Native (Expo) development with Node.js 22 (Alpine)
`blaxel/chromium:latest`	Headless Chromium environment with Chrome 124 (Alpine)
`blaxel/lightpanda:latest`	Lightweight headless browser
`blaxel/playwright-chromium:latest`	Playwright + Chromium browser automation environment with Node.js 20
`blaxel/playwright-firefox:latest`	Playwright + Firefox browser automation environment with Node.js 20
`blaxel/docker-in-sandbox:latest`	Docker-in-Docker environment
`blaxel/xfce-vnc:latest`	XFCE desktop environment with VNC
`blaxel/cua-xfce:latest`	XFCE desktop environment with CUA
`blaxel/jupyter-notebook:latest`	Jupyter Notebook with Python 3.12
`blaxel/jupyter-server:latest`	Jupyter Server with Python 3.12
`blaxel/benchmark:latest`	Sandbox benchmarking environment

Custom images

You can also customize an image for specific needs.

Create a sandbox image

You can create a customized sandbox image using the Blaxel CLI or REST API.

Blaxel CLI

1. Initialize an image

Start by creating a new sandbox image using the Blaxel CLI:

bl new sandbox mytemplate

This creates a new directory with the essential image files:

mytemplate/
├── blaxel.toml        # Image configuration
├── Makefile           # Build commands
├── Dockerfile         # Defines the sandbox environment
└── entrypoint.sh      # Initialization script

2. Customize the Dockerfile

The Dockerfile is the heart of your image. It defines what will be available in your sandbox environment.

# Choose a base image
FROM node:22-alpine

# Set working directory
WORKDIR /app

# Copy sandbox API (required)
COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api

# Install system dependencies
RUN apk update && apk add --no-cache \
	git curl python3 make g++ netcat-openbsd \
  && rm -rf /var/cache/apk/*

# Copy and set up entrypoint
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Always include the sandbox-api binary from the Blaxel base image. This is required for sandbox functionality like process management and file operations.

3. Configure image settings

The blaxel.toml file defines your image’s runtime configuration:

name = "mytemplate"
type = "sandbox"
description = "Full-stack development environment with Node.js and Python"

[runtime]
generation = "mk3"
memory = 8192             # 8GB RAM

# Define exposed ports
[[runtime.ports]]
name = "dev-server"
target = 3000
protocol = "tcp"
[[runtime.ports]]
name = "another-api"
target = 8888
protocol = "tcp"

# Set environment variables
[env]
NODE_ENV = "development"
PYTHON_ENV = "development"

Currently, it is not possible to add or update environment variables for a sandbox after it is created. Ensure that any required environment variables are defined in your Dockerfile, your blaxel.toml file, or at sandbox creation time using the Blaxel SDKs.

4. Define initialization

The entrypoint.sh script runs when a sandbox is created from this image:

#!/bin/sh

# Start the sandbox API (required)
/usr/local/bin/sandbox-api &

# Wait for sandbox API to be ready
echo "Waiting for sandbox API..."
while ! nc -z 127.0.0.1 8080; do
  sleep 0.1
done

echo "Sandbox API ready"

# Initialize your environment
echo "Setting up development environment..."

# Example: Start a development server in the background
if [ -f /app/package.json ]; then
    cd /app
    npm install
    # Execute curl command, we execute it through the sandbox-api so that you can access logs,
    # process status and everything you can do with the sandbox api
    echo "Running Next.js dev server..."
    curl http://127.0.0.1:8080/process -X POST -d '{"workingDir": "/app", "command": "npm run dev", "waitForCompletion": false}' -H "Content-Type: application/json"
fi

# Keep the container running
wait

5. Build and test locally

Before pushing the image to Blaxel, test it locally:

# Build the Docker image
make build

# Run locally to test
make run

# Access your sandbox-api on exposed ports
# e.g., http://127.0.0.1:8080
# Example: curl http://127.0.0.1:8080/process

6. Push the image

Once satisfied with your configuration, push the image to Blaxel:

bl push

This will:

Build your Docker image
Push it to Blaxel’s registry (private to your workspace)
Return an image ID you can use for creating sandboxes

Use bl deploy instead if you also want Blaxel to automatically create a first sandbox from this image, so you can test it:

bl deploy

You can monitor the sandbox deployment with:

bl get sandbox mytemplate --watch

You can safely delete the sandbox afterwards, and keep using the image for new sandboxes.

Blaxel SDK

The Blaxel SDK includes a declarative image builder that lets you define custom sandbox images directly in your code using a fluent, chainable API. Instead of writing Dockerfiles manually, you describe your image step by step, and the SDK generates the Dockerfile, builds the image, and deploys it as a sandbox. This approach is ideal for dynamic image definitions, CI/CD pipelines, or when your image configuration depends on runtime logic.

The Declarative Image Builder is available in the TypeScript and Python SDKs. The Go SDK does not support this feature.

Here is a simple example of how to use it:

import { ImageInstance } from "@blaxel/core";

const image = ImageInstance.fromRegistry("python:3.11-slim")
  .aptInstall("git", "curl")
  .workdir("/app")
  .pipInstall("requests", "httpx", "pydantic")
  .env({ PYTHONUNBUFFERED: "1" });

const sandbox = await image.build({
  name: "my-sandbox",
  memory: 4096,
});

The three steps to use the image builder are:

Define: Use the fluent API to describe your image starting from a base image.
Chain: Each method returns a new immutable ImageInstance, so you can branch and reuse configurations.
Build: Call build() to generate a Dockerfile, package it with any local files, upload it to Blaxel, and deploy it as a sandbox.

The SDK automatically injects the Blaxel sandbox API binary and sets a default entrypoint (if you haven’t specified one), so your image is ready to use as a sandbox without manual configuration.

Select a base image

Start by selecting a base image from any Docker registry:

import { ImageInstance } from "@blaxel/core";

const image = ImageInstance.fromRegistry("ubuntu:22.04");

Execute build commands

Execute shell commands during the image build:

const image = ImageInstance.fromRegistry("node:20")
  .runCommands(
    "apt-get update && apt-get install -y python3 make g++"
  );

Use package managers

The SDK provides convenience methods for common package managers. These generate optimized RUN commands with sensible defaults (e.g., cache cleanup for apt).

Python (pip)

// Simple install
const image = ImageInstance.fromRegistry("python:3.11-slim")
  .pipInstall("requests", "numpy>=1.20", "pandas");

// With options
const image = ImageInstance.fromRegistry("python:3.11-slim")
  .pipInstall(
    { indexUrl: "https://my-private-index.com/simple", pre: true },
    "my-package",
    "another-package"
  );

Python (uv)

const image = ImageInstance.fromRegistry("python:3.11-slim")
  .runCommands("pip install uv")
  .uvInstall("requests", "httpx");

Node.js (npm, yarn, pnpm, bun)

// Install specific packages with npm (default)
const image = ImageInstance.fromRegistry("node:20-alpine")
  .npmInstall("express", "typescript");

// Use a different package manager
const image = ImageInstance.fromRegistry("node:20-alpine")
  .npmInstall(
    { packageManager: "pnpm", globalInstall: true },
    "turbo"
  );

// Install from package.json (no packages specified)
const image = ImageInstance.fromRegistry("node:20-alpine")
  .workdir("/app")
  .copy("package.json", "/app/package.json")
  .npmInstall();

Install system packages (apt, apk)

// Debian/Ubuntu (apt-get)
const image = ImageInstance.fromRegistry("ubuntu:22.04")
  .aptInstall("git", "curl", "build-essential");

// Alpine (apk)
const image = ImageInstance.fromRegistry("node:20-alpine")
  .apkAdd("git", "curl", "python3");

Use other package managers

// Ruby gems
const image = ImageInstance.fromRegistry("ruby:3.2")
  .gemInstall("rails", "bundler");

// Rust crates
const image = ImageInstance.fromRegistry("rust:1.75")
  .cargoInstall({ locked: true }, "cargo-watch", "cargo-edit");

// Go packages
const image = ImageInstance.fromRegistry("golang:1.22")
  .goInstall("github.com/golangci/golangci-lint/cmd/golangci-lint@latest");

// PHP Composer
const image = ImageInstance.fromRegistry("php:8.3-cli")
  .composerInstall("laravel/framework", "guzzlehttp/guzzle");

// Python CLI tools (pipx)
const image = ImageInstance.fromRegistry("python:3.11")
  .pipxInstall("black", "ruff");

Add Dockerfile instructions

All standard Dockerfile instructions are available as methods.

Specify the working directory

const image = ImageInstance.fromRegistry("node:20")
  .workdir("/app");

Define environment variables

const image = ImageInstance.fromRegistry("python:3.11")
  .env({
    PYTHONUNBUFFERED: "1",
    APP_ENV: "production",
  });

Copy files

const image = ImageInstance.fromRegistry("node:20")
  .workdir("/app")
  .copy("package.json", "/app/package.json")
  .copy("src", "/app/src");

Expose ports

const image = ImageInstance.fromRegistry("node:20")
  .expose(3000, 8080);

Set an entrypoint

const image = ImageInstance.fromRegistry("python:3.11")
  .entrypoint("python", "-m", "uvicorn", "main:app");

Add users

const image = ImageInstance.fromRegistry("ubuntu:22.04")
  .runCommands("useradd -m appuser")
  .user("appuser");

Add labels and build arguments

const image = ImageInstance.fromRegistry("python:3.11")
  .label({ version: "1.0", maintainer: "team@example.com" })
  .arg("BUILD_ENV", "production");

Add local files

Copy files and directories from your local machine into the image:

const image = ImageInstance.fromRegistry("python:3.11")
  .workdir("/app")
  .addLocalFile("./config.json", "/app/config.json")
  .addLocalDir("./src", "/app/src");

Local files are resolved to absolute paths, included in the build context, and COPY-ed into the image. You can optionally provide a contextName (TypeScript) / context_name (Python) parameter to control the filename in the build context.

Build and deploy

Basic build

const sandbox = await image.build({
  name: "my-sandbox",
});

Build with all options

const sandbox = await image.build({
  name: "my-sandbox",
  memory: 8192,                // Memory in MB (default: 4096)
  timeout: 900000,             // Timeout in ms (default: 900000 = 15 min)  — NOTE: Python SDK uses seconds
  sandboxVersion: "latest",    // Sandbox API version
  onStatusChange: (status) => {
    console.log(`Build status: ${status}`);
  },
});

The build() method automatically:

Injects the Blaxel sandbox API binary
Sets a default entrypoint if none was specified
Packages the Dockerfile and local files into a ZIP archive
Uploads and deploys the image as a sandbox
Polls until the sandbox reaches DEPLOYED or FAILED status

Inspect the generated Dockerfile

You can preview the Dockerfile without building:

const image = ImageInstance.fromRegistry("python:3.11-slim")
  .aptInstall("git")
  .workdir("/app")
  .pipInstall("requests");

console.log(image.dockerfile);
// FROM python:3.11-slim
// RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
// WORKDIR /app
// RUN pip install requests

Write to disk

You can also write the image to a folder for manual inspection or use with bl deploy:

// Write to a specific directory
const buildDir = image.write("./output", "my-image");

// Write to a temporary directory
const tempDir = image.writeTemp();

Understand immutability and branching

Each method returns a new ImageInstance, leaving the original unchanged. This lets you create base images and branch from them:

// Define a shared base
const base = ImageInstance.fromRegistry("python:3.11-slim")
  .aptInstall("git", "curl")
  .workdir("/app");

// Branch for different use cases
const mlImage = base
  .pipInstall("torch", "transformers", "datasets")
  .env({ CUDA_VISIBLE_DEVICES: "0" });

const webImage = base
  .pipInstall("fastapi", "uvicorn", "sqlalchemy")
  .expose(8000)
  .entrypoint("python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0");

// Build both independently
const mlSandbox = await mlImage.build({ name: "ml-sandbox", memory: 16384 });
const webSandbox = await webImage.build({ name: "web-sandbox", memory: 4096 });

Example script

A complete example building a Node.js / Python development sandbox:

import { ImageInstance } from "@blaxel/core";

const sandbox = await ImageInstance.fromRegistry("node:20-bookworm-slim")
  // System dependencies
  .aptInstall("git", "curl", "build-essential")
  // Working directory
  .workdir("/app")
  // Node.js dependencies
  .npmInstall({ packageManager: "npm", globalInstall: true }, "turbo")
  // Environment
  .env({
    NODE_ENV: "development",
    EDITOR: "code",
  })
  // Expose dev server ports
  .expose(3000, 5173)
  // Build and deploy
  .build({
    name: "node-dev",
    memory: 8192,
    onStatusChange: (status) => console.log(`Status: ${status}`),
  });

console.log("Sandbox deployed:", sandbox.metadata?.name);

API reference

Methods

Method	Description
`fromRegistry` / `from_registry`	Create an image from a Docker registry base image
`runCommands` / `run_commands`	Run shell commands (`RUN`)
`workdir`	Set working directory (`WORKDIR`)
`env`	Set environment variables (`ENV`)
`copy`	Copy from build context (`COPY`)
`addLocalFile` / `add_local_file`	Add a local file to build context and image
`addLocalDir` / `add_local_dir`	Add a local directory to build context and image
`expose`	Expose ports (`EXPOSE`)
`entrypoint`	Set container entrypoint (`ENTRYPOINT`)
`user`	Set the user (`USER`)
`label`	Add labels (`LABEL`)
`arg`	Define build arguments (`ARG`)
`pipInstall` / `pip_install`	Install Python packages with pip
`uvInstall` / `uv_install`	Install Python packages with uv
`pipxInstall` / `pipx_install`	Install Python CLI apps with pipx
`aptInstall` / `apt_install`	Install Debian/Ubuntu packages
`apkAdd` / `apk_add`	Install Alpine packages
`npmInstall` / `npm_install`	Install Node.js packages (npm/yarn/pnpm/bun)
`gemInstall` / `gem_install`	Install Ruby gems
`cargoInstall` / `cargo_install`	Install Rust crates
`goInstall` / `go_install`	Install Go packages
`composerInstall` / `composer_install`	Install PHP packages
`build`	Build and deploy as a sandbox
`write`	Write image to a folder
`writeTemp` / `write_temp`	Write image to a temporary folder

Properties

Property	Description
`dockerfile`	Generated Dockerfile content
`hash`	12-character SHA256 hash of the image configuration
`baseImage` / `base_image`	Base image tag

Blaxel API

Although less common, it is also possible to create a sandbox image and sandbox by directly interacting with the Blaxel API. Ensure that you have the following:

A Blaxel API key
The workspace name, found at the bottom left corner of the Blaxel Console or via bl workspaces

1. Create a ZIP archive

Create a directory with the following project contents:

Dockerfile (required) - Defines your custom sandbox image and must include sandbox-api
Any custom scripts (e.g., entrypoint.sh for initialization logic)
Configuration files or data files as needed
Additional dependencies or binaries your sandbox requires

Here is an example of the expected project structure:

mytemplate/
├── Dockerfile             # Required - defines your image
└── entrypoint.sh          # Optional - for custom initialization

The Dockerfile is the heart of your image. It defines what will be available in your sandbox environment. See an example.
The entrypoint.sh script runs when a sandbox is created from this image. See an example.

The Dockerfile can reference and use any files included in the ZIP archive. Everything gets extracted and built together as a Docker image. Once the files are ready, create a ZIP archive containing the files:

(cd mytemplate && zip -r ../mytemplate.zip .)

2. Create a sandbox resource

Set your Blaxel API key and workspace as environment variables:

export BL_API_KEY=YOUR_API_KEY
export BL_WORKSPACE=YOUR_WORKSPACE_NAME

Make an HTTP POST request to create or update your sandbox resource. This will return an upload URL for the ZIP archive.

curl -v -X POST "https://api.blaxel.ai/v0/sandboxes?upload=true" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "blaxel.ai/v1alpha1",
    "kind": "Sandbox",
    "metadata": {
      "name": "my-sandbox"
    },
    "spec": {
      "runtime": {
        "memory": 2048
      },
      "region": "us-pdx-1"
    }
  }'

Note the upload=true query parameter in the request, which indicates intent to upload custom code. The Blaxel API returns a JSON response. The response contains an x-blaxel-upload-url response header, containing the target URL to use when uploading your image. The URL is in the response headers, not the JSON body. Example response:

HTTP/2 200
x-blaxel-upload-url: https://controlplane-prod-build-sources...

Refer to the documentation on sandbox configuration parameters for more information on the body of the POST request.

3. Upload ZIP archive

Use an HTTP PUT request to upload the ZIP file to the upload URL. Replace the placeholder URL in the command below with the value of the x-blaxel-upload-url response header received earlier.

export UPLOAD_URL="https://controlplane-prod-build-sources..."
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @mytemplate.zip

The upload is successful when you receive a 200 OK status code.

4. Monitor deployment status

After uploading, poll the sandbox status endpoint to track the build and deployment progress. Make a GET request to https://api.blaxel.ai/v0/sandboxes/<SANDBOX-NAME>, where SANDBOX-NAME is the metadata.name specified in the initial POST request.

watch -n 1 'curl -s -X GET https://api.blaxel.ai/v0/sandboxes/my-sandbox -H "Authorization: Bearer $BL_API_KEY" -H "X-Blaxel-Workspace: $BL_WORKSPACE" | jq -r ".status"'

The status field of the response will progress through these values:

Status	Description
`UPLOADING`	Code archive is being uploaded
`BUILDING`	Docker image is being built
`DEPLOYING`	Container is being deployed to the cluster
`DEPLOYED`	Sandbox is ready to use
`FAILED`	Deployment failed (check build logs)
`DEACTIVATED`	Sandbox has been deactivated

Continue polling every 3-5 seconds until the status reaches DEPLOYED or FAILED. A first sandbox from that image is automatically created on Blaxel once deployment succeeds. You can safely delete the sandbox and keep using the image for new sandboxes.

Example script

Here’s a complete example script that performs all the steps above:

#!/bin/bash

# Real deployment script that executes the documented API workflow
set -e

# Configuration
SANDBOX_NAME="my-custom-sandbox-$(date +%s)"
SOURCE_DIR="mytemplate"
ZIP_FILE="mytemplate.zip"
BASE_URL="https://api.blaxel.ai/v0"

# Colors for output
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Cleanup function
cleanup() {
  if [ -f "$ZIP_FILE" ]; then
    rm -f "$ZIP_FILE"
    echo -e "\n${GREEN}✓ Cleaned up temporary files${NC}"
  fi
}

# Set trap to cleanup on exit
trap cleanup EXIT

# Validate credentials
if [ -z "$BL_API_KEY" ]; then
  echo -e "${RED}Error: BL_API_KEY not set${NC}"
  echo "Get your API key from workspace settings and set it with:"
  echo "  export BL_API_KEY='your-api-key'"
  exit 1
fi

if [ -z "$BL_WORKSPACE" ]; then
  echo -e "${RED}Error: BL_WORKSPACE not set${NC}"
  echo "Set your workspace name with:"
  echo "  export BL_WORKSPACE='your-workspace-name'"
  exit 1
fi

# Check if source directory exists
if [ ! -d "$SOURCE_DIR" ]; then
  echo -e "${RED}Error: $SOURCE_DIR directory not found${NC}"
  exit 1
fi

# Create ZIP archive
echo -e "${BLUE}Creating ZIP archive from $SOURCE_DIR...${NC}"
cd "$SOURCE_DIR"
zip -q -r "../${ZIP_FILE}" .
cd ..

FILE_SIZE=$(wc -c < "$ZIP_FILE" | tr -d ' ')
echo -e "${GREEN}✓ ZIP archive created: $ZIP_FILE ($FILE_SIZE bytes)${NC}\n"

# Step 1: Create sandbox and get upload URL
echo -e "${BLUE}[1/4] Creating sandbox '$SANDBOX_NAME'...${NC}"

# Create temporary file for headers
HEADERS_FILE=$(mktemp)

CREATE_RESPONSE=$(curl -s -D "$HEADERS_FILE" -w "\n%{http_code}" -X POST "$BASE_URL/sandboxes?upload=true" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "blaxel.ai/v1alpha1",
    "kind": "Sandbox",
    "metadata": {
      "name": "'"$SANDBOX_NAME"'"
    },
    "spec": {
      "runtime": {
        "memory": 2048
      },
      "region": "us-pdx-1"
    }
  }')

HTTP_CODE=$(echo "$CREATE_RESPONSE" | tail -n 1)
RESPONSE_BODY=$(echo "$CREATE_RESPONSE" | sed '$d')

if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
  echo -e "${RED}✗ Failed to create sandbox (HTTP $HTTP_CODE)${NC}"
  echo "$RESPONSE_BODY" | jq . 2>/dev/null || echo "$RESPONSE_BODY"
  rm -f "$HEADERS_FILE"
  exit 1
fi

# Extract upload URL from response headers
UPLOAD_URL=$(grep -i "x-blaxel-upload-url:" "$HEADERS_FILE" | cut -d' ' -f2- | tr -d '\r\n')

if [ -z "$UPLOAD_URL" ]; then
  echo -e "${RED}✗ No upload URL received in response headers${NC}"
  rm -f "$HEADERS_FILE"
  exit 1
fi

rm -f "$HEADERS_FILE"

echo -e "${GREEN}✓ Sandbox created${NC}"
echo ""

# Step 2: Upload ZIP file
echo -e "${BLUE}[2/4] Uploading code archive ($FILE_SIZE bytes)...${NC}"
UPLOAD_RESPONSE=$(curl -s -w "%{http_code}" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary "@$ZIP_FILE")

HTTP_CODE="${UPLOAD_RESPONSE: -3}"
if [ "$HTTP_CODE" != "200" ]; then
  echo -e "${RED}✗ Upload failed with status $HTTP_CODE${NC}"
  exit 1
fi

echo -e "${GREEN}✓ Upload completed${NC}"
echo ""

# Step 3: Monitor deployment status
echo -e "${BLUE}[3/4] Monitoring deployment status...${NC}"
MAX_WAIT=900  # 15 minutes
START_TIME=$(date +%s)
LAST_STATUS=""

while true; do
  # Check timeout
  CURRENT_TIME=$(date +%s)
  ELAPSED=$((CURRENT_TIME - START_TIME))
  if [ $ELAPSED -gt $MAX_WAIT ]; then
    echo -e "${RED}✗ Deployment timed out after $MAX_WAIT seconds${NC}"
    exit 1
  fi

  # Get current status
  STATUS_RESPONSE=$(curl -s -X GET "$BASE_URL/sandboxes/$SANDBOX_NAME" \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: $BL_WORKSPACE")

  STATUS=$(echo "$STATUS_RESPONSE" | jq -r '.status // empty')

  if [ -z "$STATUS" ]; then
    echo -e "${YELLOW}Warning: Could not get status, retrying...${NC}"
    sleep 3
    continue
  fi

  # Log status changes
  if [ "$STATUS" != "$LAST_STATUS" ]; then
    echo "  Status: $STATUS"
    LAST_STATUS=$STATUS
  fi

  # Check terminal states
  if [ "$STATUS" = "DEPLOYED" ]; then
    IMAGE=$(echo "$STATUS_RESPONSE" | jq -r '.spec.runtime.image // empty')
    echo ""
    echo -e "${GREEN}🎉 Deployment complete!${NC}"
    echo "Sandbox: $SANDBOX_NAME"
    echo "Image: $IMAGE"
    echo ""

    # Step 4: Show how to use it
    echo -e "${BLUE}[4/4] How to use your sandbox:${NC}"
    echo ""
    echo "Run a command:"
    echo "  bl run sandbox $SANDBOX_NAME"
    echo ""
    echo "Get sandbox details:"
    echo "  bl get sandbox $SANDBOX_NAME"
    echo ""
    echo "View logs:"
    echo "  bl logs sandbox $SANDBOX_NAME"
    echo ""
    echo "Delete sandbox:"
    echo "  bl delete sandbox $SANDBOX_NAME"
    echo ""
    exit 0
  elif [ "$STATUS" = "FAILED" ]; then
    echo ""
    echo -e "${RED}✗ Deployment failed${NC}"
    echo ""
    echo "Check build logs with:"
    echo "  curl -X GET '$BASE_URL/sandboxes/$SANDBOX_NAME/build-logs' \\"
    echo "    -H 'Authorization: Bearer \$BL_API_KEY' \\"
    echo "    -H 'X-Blaxel-Workspace: \$BL_WORKSPACE'"
    exit 1
  elif [ "$STATUS" = "DEACTIVATED" ] || [ "$STATUS" = "DEACTIVATING" ] || [ "$STATUS" = "DELETING" ]; then
    echo ""
    echo -e "${RED}✗ Unexpected status: $STATUS${NC}"
    exit 1
  fi

  # Wait before next poll
  sleep 3
done

The script accepts a source directory path containing the Dockerfile and related code and uses it to deploy a sandbox on Blaxel. It monitors the deployment status until completion and also cleans up temporary files. To use this script, first export your API key and credentials as below:

export BL_API_KEY=YOUR-API-KEY
export BL_WORKSPACE=YOUR-WORKSPACE-NAME

Create a sandbox directory named mytemplate with your custom Dockerfile and entrypoint script:

mkdir -p mytemplate

Save and run the script as deploy-sandbox.sh (Shell), index.ts (TypeScript) or main.py (Python):

chmod +x deploy-sandbox.sh
./deploy-sandbox.sh

Use a custom image

Once an image is successfully pushed, you can spawn new sandboxes instantly by using its image ID. Use the following command to retrieve the image ID of the most recently pushed image:

# Retrieve your IMAGE_ID
bl get image sandbox/mytemplate --latest

import { SandboxInstance } from "@blaxel/core";

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox-from-template",
  image: "IMAGE_ID",
  memory: 4096,
  region: "us-pdx-1",
  ports: [{ name: "nextjs-dev", target: 3000 }, { name: "another-api", target: 8888 }]
});

Update a custom image

To update an existing custom image:

Modify your Dockerfile or configuration
Rebuild locally to test changes
Push the new version:

bl push

The new revision becomes available while the old one remains accessible. Once you have a custom image, you can share it with other workspaces in the same account, or with other accounts - for example, to promote an image from development to production without rebuilding or re-pushing, or to share an image between different teams. Only the metadata record is copied to the target workspace or account; the underlying storage stays in the source. When you share an image:

The metadata is copied to the target workspace or account, pointing to the same underlying data in the source.
The target workspace or account can use the shared image to create sandboxes, just like a locally-owned image.
Storage billing stays with the source workspace or account.
New tags pushed to the source image are automatically propagated to all workspaces and accounts it is shared with.

Shared images in the consuming workspace or account include a sourceWorkspace field. In the Blaxel Console, they are marked with a badge showing the source workspace or account name.

Prerequisites

When sharing between workspaces or accounts, you must be an administrator of the source workspace. When sharing between accounts, your share request will be completed only when it receives approval from an administrator of the target account.
The image must be locally owned in the source workspace or account. You cannot re-share an image that was shared to you from elsewhere.

Blaxel Console

To share with another workspace in the same account:

Navigate to the Images page in the source workspace.
Click the actions menu (three dots) on the image you want to share.
Select Share.
In the dialog, select the Same account tab.
Select the target workspace from the dropdown.
Click Share to confirm.

The shared image appears immediately in the target workspace’s image list. To share with another account:

Navigate to the Images page in the source workspace.
Click the actions menu (three dots) on the image you want to share.
Select Share.
In the dialog, select the Different account tab.
Select the target account from the dropdown.
Click Share to confirm.

The share request must be approved by an administrator of the target account.

Blaxel CLI

Currently, the Blaxel CLI only supports image sharing across workspaces. To share images across accounts, use the Blaxel Console or the Management API instead.

Use the bl share image command:

bl share image sandbox/<imageName> --workspace <targetWorkspace>

Sharing applies to the entire image (all tags). Tag-qualified references like sandbox/my-template:v1.0 are not accepted.

Management API

For sharing between workspaces in the same account:

curl -X POST "https://api.blaxel.ai/v0/images/sandbox/{imageName}/share" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{"targetWorkspace": "production"}'

For sharing between workspaces in different accounts:

curl -X POST "https://api.blaxel.ai/v0/images/sandbox/{imageName}/share" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $SOURCE_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "targetWorkspace": "production",
    "targetAccountId": "TARGET-ACCOUNT-ID"
  }'

The target account ID can be obtained from the Workspace settings page of the Blaxel Console.

List shared images

Blaxel Console

On the image detail page in the Blaxel Console, images shared across workspaces or accounts are listed with the option to revoke sharing for each workspace or account individually.

Management API

curl -X GET "https://api.blaxel.ai/v0/images/sandbox/{imageName}/share" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE"

Unshare an image

Unsharing removes the metadata record from the target workspace or account. The image data in the source workspace is not affected. You cannot delete an image (or individual tags) while it is shared. You must unshare from all connected workspaces or accounts first.

After unsharing, any deployments in the target workspace or account that reference the shared image will fail on their next restart or scale-up. Make sure no active deployments depend on the image before unsharing.

Blaxel Console

Navigate to the Images page in the source workspace.
Open the image detail page.
In the shared workspaces list, click Unshare next to the target workspace or account you want to revoke.

Blaxel CLI

Use the bl unshare image command:

bl unshare image sandbox/<imageName> --workspace <targetWorkspace>

Management API

curl -X DELETE "https://api.blaxel.ai/v0/images/sandbox/{imageName}/share/{targetWorkspace}" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE"

Billing

Storage billing is tied to the source workspace. Metering and costs remain with the workspace that originally pushed the image, regardless of how many workspaces or accounts it is shared with. The consuming workspace or account pays nothing for image storage of shared images.

Constraints and limitations

No re-sharing: A shared image cannot be re-shared from the consuming workspace to a third workspace or account. Only the original owner can share.
Deletion protection: You cannot delete an image (or individual tags) while it is shared with other workspaces or accounts. You must unshare from all target workspaces first.
Whole image only: Sharing applies to the entire image with all its tags. You cannot share individual tags.
Admin-only: Both sharing and unsharing require administrator permissions.

Best practices

1. Optimize for cold starts

Use smaller base images (Alpine when possible)
Minimize layers in Dockerfile
Pre-install only essential packages
Defer optional installations to runtime

2. Cache dependencies

# Good: Cache package installations
COPY package*.json ./
RUN npm ci --only=production
COPY . .

# Bad: Invalidates cache on any file change
COPY . .
RUN npm install

3. Security considerations

Don’t include secrets in images
Use Blaxel’s secrets management for sensitive data
Keep base images updated
Scan for vulnerabilities regularly

4. Resource optimization

Choose appropriate resources for your use case:

Use Case	Memory
Light development	2GB
Small web application	4GB
Full-stack web	8GB

Volume templates

Pre-populate volumes with files for faster environment setup.

Workspace access control

Understand accounts, workspaces, and admin permissions.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Agents Hosting

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Documentation Index

​What are sandbox images?

​How sandbox images work

​Pre-built images

​Custom images

​Create a sandbox image

​Blaxel CLI

1. Initialize an image

2. Customize the Dockerfile

3. Configure image settings

4. Define initialization

5. Build and test locally

6. Push the image

​Blaxel SDK

Select a base image

Execute build commands

Use package managers

Python (pip)

Python (uv)

Node.js (npm, yarn, pnpm, bun)

Install system packages (apt, apk)

Use other package managers

Add Dockerfile instructions

Specify the working directory

Define environment variables

Copy files

Expose ports

Set an entrypoint

Add users

Add labels and build arguments

Add local files

Build and deploy

Basic build

Build with all options

Inspect the generated Dockerfile

Write to disk

Understand immutability and branching

Example script

API reference

Methods

Properties

​Blaxel API

1. Create a ZIP archive

2. Create a sandbox resource

3. Upload ZIP archive

4. Monitor deployment status

Example script

​Use a custom image

​Update a custom image

​Share images across workspaces and accounts

​Prerequisites

​Share an image

​Blaxel Console

​Blaxel CLI

​Management API

​List shared images

​Blaxel Console

​Management API

​Unshare an image

​Blaxel Console

​Blaxel CLI

​Management API

​Billing

​Constraints and limitations

​Best practices

​1. Optimize for cold starts

​2. Cache dependencies

​3. Security considerations

What are sandbox images?

How sandbox images work

Pre-built images

Custom images

Create a sandbox image

Blaxel CLI

Blaxel SDK

Blaxel API

Use a custom image

Update a custom image

Share images across workspaces and accounts

Prerequisites

Share an image

Blaxel Console

Blaxel CLI

Management API

List shared images

Blaxel Console

Management API

Unshare an image

Blaxel Console

Blaxel CLI

Management API

Billing

Constraints and limitations

Best practices

1. Optimize for cold starts

2. Cache dependencies

3. Security considerations

4. Resource optimization