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.

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

Blaxel’s core backbone infrastructure (Mk 3 generation and later) relies on the same micro VMs as sandboxes run on. When you deploy agents or functions as serverless endpoints, they actually run on micro VMs under the hood. While the high-level platform meets most developers’ needs, we expose this low-level API to give full flexibility to AI builders over management of deployment locations, VM lifecycle, and resource allocation.

​

Create a sandbox

Create a new sandbox using the Blaxel SDK by specifying:

• the name of the sandbox to create
• the image to use
• the ports to expose

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

const sandbox = await SandboxInstance.create({
    metadata: {
      name: "my-sandbox"
    },
      spec: {
        runtime: {
          image: "blaxel/sandbox-hub/prod/ts-app",
          ports: [
            {
              target: 8080,
              protocol: "HTTP",
            }
          ]
        }
      }
    })
    
    
 console.log(await sandbox.fs.ls("/"))

​

Connect to a sandbox

Connect to an existing sandbox by passing the sandbox name:

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

​

Overview of sandbox lifecycle

Blaxel sandboxes start in under 20 milliseconds, and scale back down after one second of inactivity, maintaining their previous state after scaling down.

Sandboxes have either one of the following statuses:

• standby: The sandbox is created but remains idle. 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.