跳到主要内容

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
= 自动生成
此 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']
支持的 runtime。有效值：'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