跳至主要內容

BlaxelSandbox

在隔離的 Blaxel 雲端 Sandbox 中執行指令。提供安全、隔離的程式碼執行環境，並支援透過 FUSE 掛載雲端儲存空間（S3、GCS）。介面詳情請參閱 WorkspaceSandbox 介面。

安裝
「安裝」的直接連結

npm install @mastra/blaxel

使用方式
「使用方式」的直接連結

將 BlaxelSandbox 加入 Workspace，並指派給 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 SandboxInstance，可直接存取 Blaxel API。如果 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 檔案系統，讓雲端儲存空間可作為 Sandbox 內的本機目錄存取。

S3
「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
「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(),
})
On this page