RailwaySandbox
一時的に分離された Railway Sandbox でコマンドを実行します。各 Sandbox は、Railway TypeScript SDK を介してオンデマンドでプロビジョニングされる分離済み Debian Linux VM です。出力ストリーミングを伴うコマンド実行、コマンドタイムアウト、設定可能なアイドルタイムアウト、ISOLATED / PRIVATE のネットワーク分離、Railway テンプレートビルダーによるカスタムベースイメージ、チェックポイントからの復元、実行中の 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 の認証情報は、次の3つの方法のいずれかで設定します。
- シェルでエクスポート
- .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',
})
使用方法使用方法への直接リンク
Workspace に RailwaySandbox を追加して 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 モードでは、外向きインターネットアクセスのみが許可され、プライベートネットワークには接続できません。
カスタムベースイメージ（テンプレート）カスタムベースイメージ（テンプレート）への直接リンク
パッケージの事前インストールと設定手順の実行により、すべての Sandbox を準備済みの状態で起動します。Railway テンプレートビルダーを受け取るビルダーコールバックを渡してください。テンプレートは最初の start() で一度だけビルドされます。
const workspace = new Workspace({
sandbox: new RailwaySandbox({
template: t => t.withPackages('git', 'curl').run('npm i -g pnpm').workdir('/app'),
}),
})
ビルド済みの SandboxTemplate を渡すと、再ビルドせずに Sandbox 間で再利用できます。sandboxId を設定した場合、再接続では既存 Sandbox の Filesystem を使用するため、テンプレートは無視されます。
実行中の Sandbox をフォークする実行中の Sandbox をフォークするへの直接リンク
実行中の Sandbox の Filesystem を新しい独立した Sandbox へクローンします。実行中のプロセスではなく、新しく起動した状態を複製します。返される RailwaySandbox は起動済みです。
const child = await sandbox.fork({ idleTimeoutMinutes: 15 })
const result = await child.executeCommand('cat', ['/app/state.json'])
console.log(result.stdout)
fork() オプションで上書きしない限り、フォークされた Sandbox は親の認証情報とデフォルト値を継承します。
チェックポイント復元チェックポイント復元への直接リンク
Railway Sandbox の置き換え後も Filesystem を維持するには、checkpointName を設定します。start() の実行時、RailwaySandbox は最初にチェックポイントから Sandbox を作成しようとします。チェックポイントが存在しない場合は、設定済みテンプレートまたはデフォルトイメージから Sandbox を作成し、チェックポイントを取得します。
const sandbox = new RailwaySandbox({
checkpointName: 'project-session-42',
idleTimeoutMinutes: 30,
})
RailwaySandbox は、アイドルタイムアウトの直前にチェックポイントを更新します。復元時には、最後に成功したチェックポイントを使用します。実行中のプロセスや、最後のチェックポイント以降の Filesystem への書き込みは復元されません。
独立した Filesystem ごとに1つの固定チェックポイント名を使用してください。無関係なセッションやプロジェクト間でチェックポイント名を共有しないでください。
クローンした Sandbox のチェックポイントクローンした Sandbox のチェックポイントへの直接リンク
設定済みの RailwaySandbox を複数の Sandbox のテンプレートとして使用する場合は、clone({ checkpointName }) を使用します。
const template = new RailwaySandbox({ idleTimeoutMinutes: 30 })
const sessionSandbox = template.clone({
id: 'session-42',
checkpointName: 'project-session-42',
})
await sessionSandbox.start()
クローンした Sandbox は、clone() に渡したチェックポイントを使用します。上書きを渡さない場合は、テンプレート 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 で再接続します。
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 への登録への直接リンク
保存された Sandbox 設定をランタイムインスタンスとして復元できるよう、Provider を MastraEditor に登録します。
import { railwaySandboxProvider } from '@mastra/railway'
const editor = new MastraEditor({
sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
})
カスタム Sandbox Provider の登録方法は、Sandbox Provider リファレンスを参照してください。