BlaxelSandbox

分離された Blaxel クラウド Sandbox でコマンドを実行します。FUSE によるクラウドストレージ（S3、GCS）のマウントに対応した、安全で分離されたコード実行環境を提供します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。

インストール

npm

npm install @mastra/blaxel

pnpm

pnpm add @mastra/blaxel

Yarn

yarn add @mastra/blaxel

Bun

bun add @mastra/blaxel

使用方法

Workspace に BlaxelSandbox を追加して 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,
})

リソースを指定したカスタムイメージ

追加メモリを指定してカスタム Docker イメージを使用します。

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

コンストラクターパラメーター

id?:

string

= Auto-generated

この Sandbox インスタンスの一意な識別子。

image?:

string

= 'blaxel/ts-app:latest'

Sandbox で使用する Docker イメージ。Debian ベースのイメージは S3 と GCS のマウント、Alpine ベースのイメージは S3 のマウントに対応します。

memory?:

number

= 4096

割り当てるメモリ容量（MB）。

timeout?:

string

期間文字列で指定する実行タイムアウト（例：'5m'、'1h'）。Blaxel Sandbox の TTL に対応します。

region?:

string

= process.env.BL_REGION || 'auto'

Sandbox を作成する Blaxel リージョン。リージョンを自動選択するには 'auto'、明示するには 'us-pdx-1' などを指定します。

env?:

Record<string, string>

Sandbox に設定する環境変数。

labels?:

Record<string, string>

Sandbox のカスタムラベル。

runtimes?:

SandboxRuntime[]

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

対応ランタイム。有効な値：'node'、'python'、'bash'、'ruby'、'go'、'rust'、'java'、'cpp'、'r'。

ports?:

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

Sandbox から公開するポート。

プロパティ

id:

string

Sandbox インスタンスの識別子。

name:

string

'BlaxelSandbox'

provider:

string

'blaxel'

status:

ProviderStatus

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

instance:

SandboxInstance

Blaxel API へ直接アクセスするための基盤となる Blaxel SandboxInstance。Sandbox が起動していない場合は SandboxNotReadyError をスローします。

processes:

BlaxelProcessManager

バックグラウンドプロセスマネージャー。SandboxProcessManager リファレンスを参照してください。

バックグラウンドプロセス

BlaxelSandbox には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。

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

注記

Blaxel Sandbox は stdin に対応していません。handle.sendStdin() を呼び出すとエラーがスローされます。

完全な API は、SandboxProcessManager リファレンスを参照してください。

クラウドストレージのマウント

Blaxel Sandbox は S3 または GCS Filesystem をマウントし、クラウドストレージを 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(),
})