RailwaySandbox
在臨時、隔離的 Railway Sandbox 中執行指令。每個 Sandbox 都是按需要透過 Railway TypeScript SDK 配置的隔離 Debian Linux VM。支援以串流輸出執行指令、指令逾時、可設定的閒置逾時、ISOLATED／PRIVATE 網絡隔離、透過 Railway template builder 使用自訂基礎映像、以 checkpoint 為基礎的復原、fork 執行中的 Sandbox，以及按 ID 重新連接至現有 Sandbox。介面詳情請參閱 WorkspaceSandbox 介面。
安裝安裝 的直接連結
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/railway
pnpm add @mastra/railway
yarn add @mastra/railway
bun add @mastra/railway
以以下三種方式之一設定 Railway 憑證。
- Shell 匯出
- .env 檔案
- 建構函式
export RAILWAY_API_TOKEN=your-api-token
export RAILWAY_ENVIRONMENT_ID=your-environment-id
RAILWAY_API_TOKEN=your-api-token
RAILWAY_ENVIRONMENT_ID=your-environment-id
new RailwaySandbox({
token: 'your-api-token',
environmentId: 'your-environment-id',
})
用法用法 的直接連結
將 RailwaySandbox 加入 Workspace，並指派給 Agent：
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { RailwaySandbox } from '@mastra/railway'
const workspace = new Workspace({
sandbox: new RailwaySandbox({
// token + environmentId read from RAILWAY_API_TOKEN / RAILWAY_ENVIRONMENT_ID
idleTimeoutMinutes: 30,
}),
})
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,
})
const response = await agent.generate(
'Print "Hello, world!" and show the current working directory.',
)
console.log(response.text)
私有網絡私有網絡 的直接連結
加入環境的私有網絡，以連接其他 Railway 服務（例如 postgres.railway.internal）：
const workspace = new Workspace({
sandbox: new RailwaySandbox({
networkIsolation: 'PRIVATE',
env: { NODE_ENV: 'production' },
}),
})
預設的 ISOLATED 模式只允許連出互聯網，不能連接私有網絡。
自訂基礎映像（template）自訂基礎映像（template） 的直接連結
預先安裝套件並執行設定步驟，讓每個 Sandbox 啟動時都準備就緒。傳入 Railway template builder 的 builder callback；template 會在首次 start() 時建置一次：
const workspace = new Workspace({
sandbox: new RailwaySandbox({
template: t => t.withPackages('git', 'curl').run('npm i -g pnpm').workdir('/app'),
}),
})
你亦可傳入預先建置的 SandboxTemplate，在多個 Sandbox 重用而無需重新建置。設定 sandboxId 時會忽略 template，因為重新連接會使用現有 Sandbox 的檔案系統。
Fork 執行中的 SandboxFork 執行中的 Sandbox 的直接連結
將執行中 Sandbox 的檔案系統複製至全新、獨立的 Sandbox；這會重新啟動，而不會複製即時程序。傳回的 RailwaySandbox 已經啟動：
const child = await sandbox.fork({ idleTimeoutMinutes: 15 })
const result = await child.executeCommand('cat', ['/app/state.json'])
console.log(result.stdout)
除非透過 fork() 選項覆寫，否則 fork 出來的 Sandbox 會繼承父項目的憑證及預設值。
Checkpoint 復原Checkpoint 復原 的直接連結
設定 checkpointName，在 Railway 更換 Sandbox 時保留其檔案系統。執行 start() 時，RailwaySandbox 會先嘗試從 checkpoint 建立 Sandbox。如 checkpoint 不存在，便會從已設定的 template 或預設映像建立 Sandbox，然後擷取 checkpoint。
const sandbox = new RailwaySandbox({
checkpointName: 'project-session-42',
idleTimeoutMinutes: 30,
})
RailwaySandbox 會在閒置逾時前不久重新整理 checkpoint。復原時會還原最近一次成功的 checkpoint，但不會還原執行中的程序，亦不會還原上次 checkpoint 後寫入檔案系統的內容。
每個獨立檔案系統應使用一個穩定的 checkpoint 名稱。請勿在無關的工作階段或項目之間共用 checkpoint 名稱。
複製的 Sandbox checkpoint複製的 Sandbox checkpoint 的直接連結
當已設定的 RailwaySandbox 用作 Sandbox fleet 的 template 時，使用 clone({ checkpointName })：
const template = new RailwaySandbox({ idleTimeoutMinutes: 30 })
const sessionSandbox = template.clone({
id: 'session-42',
checkpointName: 'project-session-42',
})
await sessionSandbox.start()
複製的 Sandbox 會使用傳給 clone() 的 checkpoint。如沒有傳入覆寫值，便會繼承 template Sandbox 的 checkpointName。
串流輸出串流輸出 的直接連結
透過 onStdout 及 onStderr callback 即時串流指令輸出：
await sandbox.executeCommand('bash', ['-c', 'for i in 1 2 3; do echo "line $i"; sleep 1; done'], {
onStdout: chunk => process.stdout.write(chunk),
onStderr: chunk => process.stderr.write(chunk),
})
兩個 callback 均為選用，亦可獨立使用。
重新連接至現有 Sandbox重新連接至現有 Sandbox 的直接連結
Railway Sandbox 的存續時間可超過建立它的程序。以其 Railway ID 重新連接，而非配置新的 Sandbox：
const sandbox = new RailwaySandbox({ sandboxId: 'existing-railway-sandbox-id' })
await sandbox._start()
const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
建構函式參數建構函式參數 的直接連結
id?:
token?:
environmentId?:
sandboxId?:
checkpointName?:
idleTimeoutMinutes?:
networkIsolation?:
env?:
template?:
timeout?:
instructions?:
屬性屬性 的直接連結
id:
name:
provider:
status:
railway:
processes:
方法方法 的直接連結
fork:
clone:
背景程序背景程序 的直接連結
RailwaySandbox 內置程序管理器，用於產生及管理背景程序。每個產生的程序會作為 Railway exec 工作階段執行。
const sandbox = new RailwaySandbox()
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()
Railway 的 exec API 不會串流 stdin，因此不支援 sendStdin()。
完整 API 請參閱 SandboxProcessManager 參考。
Editor ProviderEditor Provider 的直接連結
向 MastraEditor 註冊 Provider，以將已儲存的 Sandbox 設定載入為執行階段實例：
import { railwaySandboxProvider } from '@mastra/railway'
const editor = new MastraEditor({
sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
})
有關註冊自訂 Sandbox Provider 的詳情，請參閱 Sandbox Provider 參考。