Build reusable sandbox images with Dockerfiles

Create reusable sandbox images with pre-configured tools, languages, and frameworks using Dockerfiles. Deploy new sandboxes from images in seconds.

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 review agent, etc.).

To free storage occupied by images you no longer use, see clean up unused images.

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

1. Initial setup: Follow this guide to create your sandbox image for the first time. Use bl push to publish the image to Blaxel’s registry without creating a new sandbox or affecting existing sandboxes, or bl deploy to push the image and also create a sandbox from it.
2. Build phase: Your Dockerfile is used to create a container with all required tools and configurations. Blaxel then slims the image, removing files that are usually only needed at build time.
3. Initialization phase: The sandbox API is injected and startup commands are executed.
4. 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/claude-code:latest	Claude Code CLI environment with Node.js 24 (slim)
blaxel/codex:latest	Codex CLI environment with Node.js 24 (slim)
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 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.

This example installs make and g++. Those compilers are available in RUN steps, then removed by image slimming before the sandbox starts. Set slim = false when the running sandbox needs them.

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"

Variables set here apply to every sandbox created from this image. On the new sandbox generation, you can also update variables on a running sandbox or give them a new value when you fork a sandbox. See the variables and secrets documentation for details.

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:

1. Build your Docker image
2. Push it to Blaxel’s registry (private to your workspace)
3. 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:

TypeScript

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:

1. Define: Use the fluent API to describe your image starting from a base image.
2. Chain: Each method returns a new immutable ImageInstance, so you can branch and reuse configurations.
3. 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:

TypeScript

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

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

Execute build commands

Execute shell commands during the image build:

TypeScript

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)

TypeScript

// 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)

TypeScript

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

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

TypeScript

// 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)

TypeScript

// 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

TypeScript

// 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

TypeScript

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

Define environment variables

TypeScript

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

Copy files

TypeScript

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

Expose ports

TypeScript

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

Set an entrypoint

TypeScript

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

Add users

TypeScript

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

Add labels and build arguments

TypeScript

const image = ImageInstance.fromRegistry("python:3.11")
  .label({ version: "1.0", maintainer: "[e-mail]" })
  .arg("BUILD_ENV", "production");

Add local files

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

TypeScript

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

TypeScript

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

Build with all options

TypeScript

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
• Runs the default image slimming pass after the Docker build
• Polls until the sandbox reaches DEPLOYED or FAILED status

Inspect the generated Dockerfile

You can preview the Dockerfile without building:

TypeScript

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:

TypeScript

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

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

Size the build environment

Large images can run out of memory or disk while they build. Set buildMemory and buildVolume (build_memory and build_volume in Python) on build() to size the temporary environment the image is built in. These are the same settings as bl push --memory and --volume, or [build].memoryMb and [build].volumeMb in blaxel.toml.

TypeScript

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

Option	Range (MB)	Description
buildMemory / build_memory	1 to 32768	Memory of the build environment
buildVolume / build_volume	0 to 131072	Disk attached to the build for its intermediate layers. 0 builds in memory

When you omit them, the platform defaults apply. They only affect the build. The deployed sandbox uses memory.

These options require @blaxel/core 0.3.28 or later, or blaxel 0.4.16 or later. HIPAA workspaces do not support buildVolume; omit it or set it to 0.

Understand immutability and branching

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

TypeScript

// 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", "::");

// 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:

TypeScript

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. See Size the build environment for build options
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)

See sandbox deployment statuses for the full list of statuses a sandbox can report outside of this initial deployment flow.

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:

Shell

#!/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 the sandbox status for error details:"
    echo "  curl -s -X GET '$BASE_URL/sandboxes/$SANDBOX_NAME' \\"
    echo "    -H 'Authorization: Bearer \$BL_API_KEY' \\"
    echo "    -H 'X-Blaxel-Workspace: \$BL_WORKSPACE' | jq ."
    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):

Shell

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

Deploy from a private registry

Instead of building from source, you can point blaxel.toml directly at an image in a private registry:

type = "sandbox"
name = "my-custom-sandbox"
image = "docker.io/myuser/my-sandbox:latest"

[runtime]
memory = 4096

The image must include the sandbox API binary.

You can then push or deploy the image using bl push or bl deploy as usual.

To configure registry credentials, you have three options (listed in priority order):

1. Pass the credentials inline to bl push or bl deploy with the --registry-cred flag

   bl push --image docker.io/myuser/my-sandbox:latest --name my-custom-sandbox  --registry-cred "docker.io=myuser:mypassword"
   

2. Pass the credentials from a different configuration file to bl push or bl deploy with the --docker-config flag

   bl push --image docker.io/myuser/my-sandbox:latest --name my-custom-sandbox --docker-config ~/.docker/config.json
   

3. Place a .docker/config.json in your project directory using the standard Docker config format (you can copy your existing ~/.docker/config.json). The file will be automatically detected and used by bl push or bl deploy.

   Add .docker/config.json to your .gitignore to avoid committing registry credentials to source control.
   {
     "auths": {
       "docker.io": {
         "auth": "<base64 of username:password>"
       }
     }
   }
   

The following registries are currently supported:

• Docker Hub
• GitHub Container Registry
• Google Artifact Registry
• Amazon ECR
• Any private registry which supports Basic auth

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

TypeScript

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 }]
});

Run the workload as a non-root user

Everything in a sandbox runs as root by default. To scope processes, terminals and filesystem operations to an unprivileged user while the sandbox API keeps the privileges it needs, declare the user in your Dockerfile and enable the feature:

RUN adduser -D -u 10001 -h /blaxel app
USER app
ENV BL_SANDBOX_USER_ENABLED=true

See running sandbox workloads as a non-root user for the entrypoint variant, what stays privileged, and the limitations.

Update a custom image

To update an existing custom image:

1. Modify your Dockerfile or configuration
2. Rebuild locally to test changes
3. Push the new version:

bl push

The new revision becomes available while the old one remains accessible.

Image slimming

After the Docker build finishes, Blaxel runs a slimming pass on the image root filesystem. The pass reduces image size and sandbox boot time. It removes a fixed list of paths that are typically only needed while the image is building:

• package manager caches
• documentation and man pages
• headers and static libraries
• systemd
• Python __pycache__ directories
• build toolchains, including make, gcc, g++, cmake, autoconf, and automake

The same paths are removed from every image. RUN instructions can still use these tools while the image is building. The tools are absent when a sandbox starts from the published image.

bl push and bl deploy run this pass. Local docker build and make run keep the filesystem Docker produced. A binary can exist in that local container and be missing from the sandbox. The SDK build() method uploads the image to the same pipeline, so the pass runs there too.

Slimming is enabled by default. For images you publish with bl push or bl deploy, disable it in blaxel.toml when the running sandbox needs a compiler or another build tool:

[build]
slim = false

With slim = false, the image keeps caches, documentation, headers, and build tools. The image is larger. Sandboxes take longer to boot. Leave slimming enabled when those files are only needed to compile dependencies during the image build.

Clean up unused images

Use the Blaxel Console to delete unused image tags in bulk and free image storage. This is useful after repeated builds or when you approach your total image-size quota. Check your account’s limits on the Quotas page.

Cleanup applies to the selected workspace, across resource types, not only sandbox images. Image tags referenced by existing resources are kept, including those used by sandboxes on standby. Unused tags can be deleted even when another tag of the same image is still in use.

Cleanup permanently deletes unused image tags and cannot be undone. An image pushed with bl push but not referenced by a resource can be deleted, even if you plan to use it later. Review any images or old tags you want to keep for future deployments before confirming.

To clean up images:

1. Open the Blaxel Console and select the workspace you want to clean up.
2. In the sidebar, open Sandboxes > Images. Review the images and their Total size values.
3. Click Cleanup Unused to open the Cleanup Unused Images dialog.
4. Review the warning and type cleanup in the confirmation field.
5. Click Cleanup Images to delete unused image tags.

The image list refreshes after cleanup. If image storage is still near your quota, review the remaining images and their tags to identify what you still need. Cleanup does not delete your sandboxes or other resources.

Share images across workspaces and accounts

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:

1. The metadata is copied to the target workspace or account, pointing to the same underlying data in the source.
2. The target workspace or account can use the shared image to create sandboxes, just like a locally-owned image.
3. Storage billing stays with the source workspace or account.
4. 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.

Share an image

Blaxel Console

To share with another workspace in the same account:

1. Navigate to the Images page in the source workspace.

2. Click the actions menu (three dots) on the image you want to share.

3. Select Share.

4. In the dialog, select the Same account tab.

5. Select the target workspace from the dropdown.

6. Click Share to confirm.

   

The shared image appears immediately in the target workspace’s image list.

To share with another account:

1. Navigate to the Images page in the source workspace.

2. Click the actions menu (three dots) on the image you want to share.

3. Select Share.

4. In the dialog, select the Different account tab.

5. Select the target account from the dropdown.

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

1. Navigate to the Images page in the source workspace.
2. Open the image detail page.
3. 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
• Leave image slimming enabled unless the sandbox needs build tools at 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.