Sandboxes are fast-launching virtual machines that both humans and AI agents can operate. They provide a basic REST API interface for accessing the file system and processes, along with an MCP server that makes these capabilities available to agents. They natively serve as sandboxed compute runtimes for agents. You can securely run untrusted code inside these VMs — particularly AI-generated code — making them ideal for coding agents that need access to an operating system to run commands with no risk of escaping. Blaxel sandboxes start from hibernation state in under 25 milliseconds, and scale back down to zero after one second of inactivity, maintaining the memory state even after scaling down. This includes all filesystem as well as running processes.

​
Create a sandbox

Create a new sandbox using the Blaxel SDK by specifying a name, the image to use and the ports to expose. Note that ports 80 (system), and 443 & 8080 (sandbox API) are reserved by Blaxel. 
import { SandboxInstance } from "@blaxel/core";

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/prod-base:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }]
});

// Wait for deployment
await sandbox.wait();
While SandboxInstance.create() waits for the creation to be acknowledged, the function sandbox.wait allows to wait for the sandbox to be fully deployed and ready on Blaxel.

​
Images

The list of public images can be found here. To create a sandbox with one of those images, enter blaxel/prod-{NAME}:latest (e.g. blaxel/prod-base:latest).
Custom sandbox images (or templates) enable you to create sandboxes with a consistent, customized set of tools, configurations, or entrypoint scripts.

​
Ports

The following ports are reserved by Blaxel’s system:
  • 443: This port hosts the main sandbox API and is exposed via HTTPS
  • 80: Reserved for system operations
  • 8080: Reserved for sandbox API functionality
You can expose specific non-reserved ports when creating a new sandbox by using the ports parameter.

​
Expiration date

Set time-to-live (TTL) on the sandbox to automatically delete it after a specific period using the ttl parameter, or at a specific date using the expiresAt/expires_at parameter. The ttl parameter accepts a string with the following time units: s (seconds), m (minutes), h (hours), d (days), and w (weeks).
This differs from the automatic shut down (scale-to-zero) which happens to all sandboxes when inactive and where the memory and filesystem are snapshotted to be resumed instantly.

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

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/prod-base:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }],
  ttl: "60s", // Total duration before auto-deletion. Supported units: s, m, h, d, w
  // OR
  // expiresAt: new Date(Date.now() + 60000) // Alternative: set a date at which it will be deleted
});

// Wait for deployment
await sandbox.wait();

​
Retrieve an existing sandbox

To reconnect to an existing sandbox, simply provide its name: 
import { SandboxInstance } from "@blaxel/core";

// Connect to existing sandbox
const sandbox = await SandboxInstance.get("my-sandbox");
Complete code examples demonstrating all operations are available on Blaxel’s GitHub: in TypeScript and in Python.

​
Create if not exists

This helper function either retrieves an existing sandbox or creates a new one if it doesn’t exist. Blaxel first checks for an existing sandbox with the provided name and either retrieves it or creates a new one using your specified configuration. 
import { SandboxInstance } from "@blaxel/core";

// Create sandbox if it doesn't exist
const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-sandbox",
  image: "blaxel/prod-base:latest",
  memory: 4096,
  ports: [{ target: 3000, protocol: "HTTP" }]
});

await sandbox.wait();

​
Connect to a sandbox with a terminal

You can explore the contents of a sandbox with a terminal-like interface by running: 
bl connect sandbox your-sandbox-name
image.png While not a true SSH connection, this interface lets you list and manage files, and execute commands as you would in a traditional terminal.

​
MCP server for a sandbox

Every sandbox is also exposed via an MCP server that allows agents to operate a sandbox using tool calls. The MCP server operates through WebSockets at the sandbox’s base URL: 
wss://run.blaxel.ai/{{WORKSPACE_ID}}/sandboxes/{{SANDBOX_ID}}
Connect to this MCP server like any other MCP server though the endpoint shown above. Using Blaxel SDK, you can retrieve the tools for a sandbox in any supported framework format by passing the sandbox’s name. For example, in LangGraph: 
import { blTools } from "@blaxel/vercel";

const tools = await blTools([`sandbox/${sandboxName}`])
Read more documentation on connecting to the MCP server directly from your code.

​
Sandbox statuses

Blaxel sandboxes start from standby to active in under 25 milliseconds, and scale back down top standby after one second of inactivity, maintaining their previous state after scaling down. Here is the summary on the possible statuses for a sandbox:
  • standby: The sandbox is created but is hibernating. You are not charged while a sandbox is in standby mode. Sandboxes transition from standby to active mode in approximately 20 ms.
  • active: The sandbox is running and processing tasks. You are charged for active runtime. Sandboxes automatically return to standby mode after 1 second of inactivity.
  • stopped: The sandbox is shut down and requires manual restart to access its API.

Processes and commands

Execute and manage processes in sandboxes.

File system operations

Manage directories and files in sandboxes.

Tools for AI codegen

Manage codebases with tools specifically designed for code generation.

Log streaming

Access logs generated in a sandbox.

Ports

Expose and connect to ports of a sandbox.

Preview in real-time

Render code in real-time via a direct preview URL.

Sessions

Manage temporary sessions to connect to sandboxes from a frontend client.

Templates

Create custom sandbox templates.
Or explore the Sandbox API reference:

Sandbox API

Access the your sandbox with an HTTP REST API.