Sandboxes

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 environments for agents. You can securely run untrusted code inside these VMs — particularly AI-generated code. This makes sandboxes ideal for codegen agents that need access to an operating system to run commands or code, without compromising security and for other users. Beyond code generation, they can just be used as general-purpose VMs for any kind of workload.

​

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 port 8080 is the sandbox API, it is automatically exposed by Blaxel sandboxes.

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

/// Start sandbox creation
const sandbox = await SandboxInstance.create({
    metadata: {
        name: "my-sandbox"
    },
    spec: {
        runtime: {
            memory: 4096,
            image: "blaxel/prod-base:latest"
        }
    }
})

/// Wait for the sandbox to be deployed (for max 120 seconds, checking every 1 second)
await sandbox.wait({ maxWait: 120000, interval: 1000 })

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

Custom images are currently not supported. Contact us to host your own image.

​

Retrieve an existing sandbox

To reconnect to an existing sandbox, simply provide its name:

const sandbox = await SandboxInstance.get("my-sandbox")

​

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.

const sandbox = await SandboxInstance.createIfNotExists({
    metadata: {
        name: "my-sandbox"
    },
    spec: {
        runtime: {
            memory: 4096,
            image: "blaxel/prod-base:latest"
        }
    }
})

​

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/langgraph";

const tools = await blTools([`sandbox/${sandboxName}`])

Read more documentation on connecting to the MCP server directly from your code.

​

Overview of sandbox lifecycle

Blaxel sandboxes start from standby to active in under 20 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.

Or explore the Sandbox API reference: