RailwaySandbox
在暫存且隔離的 Railway Sandbox 中執行指令。每個 Sandbox 都是透過 Railway TypeScript SDK 依需求佈建的隔離 Debian Linux VM。支援串流輸出的指令執行、指令逾時、可設定的閒置逾時、ISOLATED/PRIVATE 網路隔離、透過 Railway template builder 使用自訂基礎映像、由 checkpoint 支援的復原、分叉執行中的 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）」的直接連結
預先安裝 package 並執行設定步驟，讓每個 Sandbox 啟動後即可使用。將 builder 回呼函式傳給 Railway template builder；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 的檔案系統。
分叉執行中的 Sandbox「分叉執行中的 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() 選項覆寫，否則分叉的 Sandbox 會繼承父層的憑證與預設值。
Checkpoint 復原「Checkpoint 復原」的直接連結
設定 checkpointName 可在 Railway Sandbox 更換時保留 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 叢集的 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 回呼函式即時串流傳輸指令輸出：
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),
})
兩個回呼函式都是選用，且可獨立使用。
重新連接現有 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 Provider「Editor Provider」的直接連結
在 MastraEditor 中註冊 Provider，將儲存的 Sandbox 設定實體化為執行階段的執行個體：
import { railwaySandboxProvider } from '@mastra/railway'
const editor = new MastraEditor({
sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
})
如需註冊自訂 Sandbox Provider 的詳細資訊，請參閱 Sandbox Provider 參考。