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

npm install @mastra/blaxel

pnpm

pnpm add @mastra/blaxel

Yarn

yarn add @mastra/blaxel

Bun

bun add @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

id?:

string

= Auto-generated

Unique identifier for this sandbox instance.

image?:

string

= 'blaxel/ts-app:latest'

Docker image to use for the sandbox. Debian-based images support both S3 and GCS mounts. Alpine-based images support S3 mounts only.

memory?:

number

= 4096

Memory allocation in MB.

timeout?:

string

Execution timeout as a duration string (e.g. '5m', '1h'). Maps to the Blaxel sandbox TTL.

env?:

Record<string, string>

Environment variables to set in the sandbox.

labels?:

Record<string, string>

Custom labels for the sandbox.

runtimes?:

SandboxRuntime[]

= ['node', 'python', 'bash']

Supported runtimes. Valid values: 'node', 'python', 'bash', 'ruby', 'go', 'rust', 'java', 'cpp', 'r'.

ports?:

Array<{ name?: string; target: number; protocol?: 'HTTP' | 'TCP' | 'UDP' }>

Ports to expose from the sandbox.

Properties

id:

string

Sandbox instance identifier.

name:

string

'BlaxelSandbox'

provider:

string

'blaxel'

status:

ProviderStatus

'pending' | 'initializing' | 'running' | 'stopped' | 'error'

instance:

SandboxInstance

The underlying Blaxel SandboxInstance for direct access to Blaxel APIs. Throws SandboxNotReadyError if the sandbox has not been started.

processes:

BlaxelProcessManager

Background process manager. See [SandboxProcessManager reference](/reference/workspace/process-manager).

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(),
})