> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# RailwaySandbox

一時的に分離された [Railway](https://docs.railway.com/sandboxes) Sandbox でコマンドを実行します。各 Sandbox は、Railway TypeScript SDK を介してオンデマンドでプロビジョニングされる分離済み Debian Linux VM です。出力ストリーミングを伴うコマンド実行、コマンドタイムアウト、設定可能なアイドルタイムアウト、`ISOLATED` / `PRIVATE` のネットワーク分離、Railway テンプレートビルダーによるカスタムベースイメージ、チェックポイントからの復元、実行中の Sandbox のフォーク、ID による既存 Sandbox への再接続に対応します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/railway
```

**pnpm**:

```bash
pnpm add @mastra/railway
```

**Yarn**:

```bash
yarn add @mastra/railway
```

**Bun**:

```bash
bun add @mastra/railway
```

Railway の認証情報は、次の3つの方法のいずれかで設定します。

**シェルでエクスポート**:

```bash
export RAILWAY_API_TOKEN=your-api-token
export RAILWAY_ENVIRONMENT_ID=your-environment-id
```

**.env ファイル**:

```bash
RAILWAY_API_TOKEN=your-api-token
RAILWAY_ENVIRONMENT_ID=your-environment-id
```

**コンストラクター**:

```typescript
new RailwaySandbox({
  token: 'your-api-token',
  environmentId: 'your-environment-id',
})
```

## 使用方法

Workspace に `RailwaySandbox` を追加して Agent に割り当てます。

```typescript
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`）へアクセスします。

```typescript
const workspace = new Workspace({
  sandbox: new RailwaySandbox({
    networkIsolation: 'PRIVATE',
    env: { NODE_ENV: 'production' },
  }),
})
```

デフォルトの `ISOLATED` モードでは、外向きインターネットアクセスのみが許可され、プライベートネットワークには接続できません。

### カスタムベースイメージ（テンプレート）

パッケージの事前インストールと設定手順の実行により、すべての Sandbox を準備済みの状態で起動します。Railway テンプレートビルダーを受け取るビルダーコールバックを渡してください。テンプレートは最初の `start()` で一度だけビルドされます。

```typescript
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 の Filesystem を新しい独立した Sandbox へクローンします。実行中のプロセスではなく、新しく起動した状態を複製します。返される `RailwaySandbox` は起動済みです。

```typescript
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 を作成し、チェックポイントを取得します。

```typescript
const sandbox = new RailwaySandbox({
  checkpointName: 'project-session-42',
  idleTimeoutMinutes: 30,
})
```

`RailwaySandbox` は、アイドルタイムアウトの直前にチェックポイントを更新します。復元時には、最後に成功したチェックポイントを使用します。実行中のプロセスや、最後のチェックポイント以降の Filesystem への書き込みは復元されません。

独立した Filesystem ごとに1つの固定チェックポイント名を使用してください。無関係なセッションやプロジェクト間でチェックポイント名を共有しないでください。

### クローンした Sandbox のチェックポイント

設定済みの `RailwaySandbox` を複数の Sandbox のテンプレートとして使用する場合は、`clone({ checkpointName })` を使用します。

```typescript
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` コールバックを介して、コマンド出力をリアルタイムでストリーミングします。

```typescript
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 に再接続する

Railway Sandbox は、作成元のプロセスが終了しても存続します。新しくプロビジョニングせず、Railway ID で再接続します。

```typescript
const sandbox = new RailwaySandbox({ sandboxId: 'existing-railway-sandbox-id' })
await sandbox._start()

const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
```

## コンストラクターパラメーター

**id** (`string`): この Sandbox インスタンスの一意な識別子。 (Default: `Auto-generated`)

**token** (`string`): 認証用の Railway API トークン。未指定の場合は環境変数 RAILWAY\_API\_TOKEN を使用します。

**environmentId** (`string`): Railway 環境 ID。未指定の場合は環境変数 RAILWAY\_ENVIRONMENT\_ID を使用します。

**sandboxId** (`string`): 新しい Sandbox を作成せず、Railway ID で既存の Railway Sandbox へ再接続します。設定すると、start() が Sandbox.connect() を呼び出します。

**checkpointName** (`string`): 新しい Sandbox の作成元として使用し、アイドル状態による破棄前に Filesystem を保持する名前付き Railway チェックポイント。独立した Filesystem ごとに一意の固定名を使用してください。

**idleTimeoutMinutes** (`number`): Railway が Sandbox を自動的に破棄するまで、exec 操作なしでアイドル状態を維持できる時間。有効な範囲とデフォルト値は Railway プランによって異なります。

**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): ネットワークアクセスモード。'ISOLATED' は外向きインターネットアクセスのみを許可し、'PRIVATE' は環境のプライベートネットワークに接続します。 (Default: `'ISOLATED'`)

**env** (`Record<string, string>`): Sandbox に組み込み、すべてのコマンドから利用できる環境変数。 (Default: `{}`)

**template** (`SandboxTemplate | (base: SandboxTemplate) => SandboxTemplate`): Railway テンプレートビルダーで作成したカスタムベースイメージから Sandbox をプロビジョニングします。ビルダーコールバックまたはビルド済みテンプレートを指定できます。sandboxId が設定されている場合は無視されます。

**timeout** (`number`): 独自のタイムアウトを指定しないコマンドに適用するデフォルトの実行タイムアウト（ミリ秒）。省略すると、コマンドは終了するまで実行されます。

**instructions** (`string | (opts) => string`): Agent のデフォルト指示を上書きします。文字列は完全に置き換え、関数はデフォルト指示を受け取って最終テキストを返します。

## プロパティ

**id** (`string`): Sandbox インスタンスの識別子。

**name** (`string`): Provider 名（'RailwaySandbox'）。

**provider** (`string`): Provider 識別子（'railway'）。

**status** (`ProviderStatus`): 'pending' | 'initializing' | 'ready' | 'stopped' | 'destroyed' | 'error'

**railway** (`Sandbox`): SDK へ直接アクセスするための基盤となる Railway Sandbox インスタンス。Sandbox が起動していない場合は SandboxNotReadyError をスローします。

**processes** (`RailwayProcessManager`): バックグラウンドプロセスマネージャー。SandboxProcessManager リファレンスを参照してください。

## メソッド

**fork** (`(options?) => Promise<RailwaySandbox>`): 実行中のこの Sandbox を、新しい独立した RailwaySandbox へクローンします。返される Sandbox は起動済みで、フォークされた Railway Sandbox へ再接続されています。任意で id、idleTimeoutMinutes、networkIsolation、env を上書きできます。この Sandbox が起動していない場合は SandboxNotReadyError をスローします。

**clone** (`(options?) => RailwaySandbox`): 認証情報とデフォルト値を継承した未起動の同階層 Sandbox を構築します。任意で id、sandboxId、env、idleTimeoutMinutes、checkpointName を上書きできます。クローンした Sandbox は、options.checkpointName が設定されていればその値を使用し、それ以外はテンプレートの checkpointName を継承します。

## バックグラウンドプロセス

`RailwaySandbox` には、バックグラウンドプロセスを起動・管理するプロセスマネージャーが組み込まれています。起動した各プロセスは Railway の `exec` セッションとして動作します。

```typescript
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` リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/process-manager)を参照してください。

## Editor Provider への登録

保存された Sandbox 設定をランタイムインスタンスとして復元できるよう、Provider を `MastraEditor` に登録します。

```typescript
import { railwaySandboxProvider } from '@mastra/railway'

const editor = new MastraEditor({
  sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
})
```

カスタム Sandbox Provider の登録方法は、[Sandbox Provider リファレンス](https://mastra.zisheng.pro/ja/reference/editor/sandbox-provider)を参照してください。