import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem";

BlaxelSandbox

Executes commands in isolated Blaxel cloud sandboxes. Provides secure, isolated code execution environments with support for mounting cloud storage (S3, GCS) via FUSE.

:::info

For interface details, see WorkspaceSandbox interface.

:::

Installation

npm install @mastra/blaxel

Usage

Add a BlaxelSandbox to a workspace and assign it to an agent:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  sandbox: new BlaxelSandbox(),
})

const agent = new Agent({
  id: 'code-agent',
  name: 'Code Agent',
  instructions: 'You are a coding assistant working in this workspace.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

Custom image with resources

Use a custom Docker image with additional memory:

const workspace = new Workspace({
  sandbox: new BlaxelSandbox({
    image: 'node:20-slim',
    memory: 8192,
    timeout: '10m',
  }),
})

Constructor parameters

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Unique identifier for this sandbox instance.', isOptional: true, defaultValue: 'Auto-generated', }, { name: 'image', type: 'string', description: 'Docker image to use for the sandbox. Debian-based images support both S3 and GCS mounts. Alpine-based images support S3 mounts only.', isOptional: true, defaultValue: "'blaxel/ts-app:latest'", }, { name: 'memory', type: 'number', description: 'Memory allocation in MB.', isOptional: true, defaultValue: '4096', }, { name: 'timeout', type: 'string', description: "Execution timeout as a duration string (e.g. '5m', '1h'). Maps to the Blaxel sandbox TTL.", isOptional: true, }, { name: 'env', type: 'Record<string, string>', description: 'Environment variables to set in the sandbox.', isOptional: true, }, { name: 'labels', type: 'Record<string, string>', description: 'Custom labels for the sandbox.', isOptional: true, }, { name: 'runtimes', type: 'SandboxRuntime[]', description: "Supported runtimes. Valid values: 'node', 'python', 'bash', 'ruby', 'go', 'rust', 'java', 'cpp', 'r'.", isOptional: true, defaultValue: "['node', 'python', 'bash']", }, { name: 'ports', type: "Array<{ name?: string; target: number; protocol?: 'HTTP' | 'TCP' | 'UDP' }>", description: 'Ports to expose from the sandbox.', isOptional: true, }, ]} />

Properties

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Sandbox instance identifier.', }, { name: 'name', type: 'string', description: "'BlaxelSandbox'", }, { name: 'provider', type: 'string', description: "'blaxel'", }, { name: 'status', type: 'ProviderStatus', description: "'pending' | 'initializing' | 'running' | 'stopped' | 'error'", }, { name: 'instance', type: 'SandboxInstance', description: 'The underlying Blaxel SandboxInstance for direct access to Blaxel APIs. Throws SandboxNotReadyError if the sandbox has not been started.', }, { name: 'processes', type: 'BlaxelProcessManager', description: 'Background process manager. See SandboxProcessManager reference.', }, ]} />

Background processes

BlaxelSandbox includes a built-in process manager for spawning and managing background processes.

const sandbox = new BlaxelSandbox({ id: 'dev-sandbox' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// Interact with the process
console.log(handle.stdout)
await handle.kill()

:::note Blaxel sandboxes don't support stdin. Calling handle.sendStdin() throws an error. :::

See SandboxProcessManager reference for the full API.

Mounting cloud storage

Blaxel sandboxes can mount S3 or GCS filesystems, making cloud storage accessible as a local directory inside the sandbox.

S3

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
  },
  sandbox: new BlaxelSandbox(),
})

GCS

import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { BlaxelSandbox } from '@mastra/blaxel'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-bucket',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY!),
    }),
  },
  sandbox: new BlaxelSandbox(),
})