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

# RailwaySandbox

在臨時、隔離的 [Railway](https://docs.railway.com/sandboxes) Sandbox 中執行指令。每個 Sandbox 都是按需要透過 Railway TypeScript SDK 配置的隔離 Debian Linux VM。支援以串流輸出執行指令、指令逾時、可設定的閒置逾時、`ISOLATED`／`PRIVATE` 網絡隔離、透過 Railway template builder 使用自訂基礎映像、以 checkpoint 為基礎的復原、fork 執行中的 Sandbox，以及按 ID 重新連接至現有 Sandbox。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/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 憑證。

**Shell 匯出**:

```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',
})
```

## 用法

將 `RailwaySandbox` 加入 Workspace，並指派給 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` 模式只允許連出互聯網，不能連接私有網絡。

### 自訂基礎映像（template）

預先安裝套件並執行設定步驟，讓每個 Sandbox 啟動時都準備就緒。傳入 Railway template builder 的 builder callback；template 會在首次 `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` 時會忽略 template，因為重新連接會使用現有 Sandbox 的檔案系統。

### Fork 執行中的 Sandbox

將執行中 Sandbox 的檔案系統複製至全新、獨立的 Sandbox；這會重新啟動，而不會複製即時程序。傳回的 `RailwaySandbox` 已經啟動：

```typescript
const child = await sandbox.fork({ idleTimeoutMinutes: 15 })

const result = await child.executeCommand('cat', ['/app/state.json'])
console.log(result.stdout)
```

除非透過 `fork()` 選項覆寫，否則 fork 出來的 Sandbox 會繼承父項目的憑證及預設值。

### Checkpoint 復原

設定 `checkpointName`，在 Railway 更換 Sandbox 時保留其檔案系統。執行 `start()` 時，`RailwaySandbox` 會先嘗試從 checkpoint 建立 Sandbox。如 checkpoint 不存在，便會從已設定的 template 或預設映像建立 Sandbox，然後擷取 checkpoint。

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

`RailwaySandbox` 會在閒置逾時前不久重新整理 checkpoint。復原時會還原最近一次成功的 checkpoint，但不會還原執行中的程序，亦不會還原上次 checkpoint 後寫入檔案系統的內容。

每個獨立檔案系統應使用一個穩定的 checkpoint 名稱。請勿在無關的工作階段或項目之間共用 checkpoint 名稱。

### 複製的 Sandbox checkpoint

當已設定的 `RailwaySandbox` 用作 Sandbox fleet 的 template 時，使用 `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()` 的 checkpoint。如沒有傳入覆寫值，便會繼承 template Sandbox 的 `checkpointName`。

### 串流輸出

透過 `onStdout` 及 `onStderr` callback 即時串流指令輸出：

```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),
})
```

兩個 callback 均為選用，亦可獨立使用。

### 重新連接至現有 Sandbox

Railway Sandbox 的存續時間可超過建立它的程序。以其 Railway ID 重新連接，而非配置新的 Sandbox：

```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: `自動產生`)

**token** (`string`): 用於驗證的 Railway API token。後備使用 RAILWAY\_API\_TOKEN 環境變數。

**environmentId** (`string`): Railway 環境 ID。後備使用 RAILWAY\_ENVIRONMENT\_ID 環境變數。

**sandboxId** (`string`): 按 Railway ID 重新連接至現有 Railway Sandbox，而非建立新的 Sandbox。設定後，start() 會呼叫 Sandbox.connect()。

**checkpointName** (`string`): 具名 Railway checkpoint，用於作為新 Sandbox 的初始內容，並在閒置拆除前保留檔案系統。請為每個獨立檔案系統使用唯一且穩定的名稱。

**idleTimeoutMinutes** (`number`): Sandbox 可維持閒置（沒有 exec 互動）多長時間，之後 Railway 會自動銷毀它。有效範圍及預設值取決於你的 Railway 方案。

**networkIsolation** (`'ISOLATED' | 'PRIVATE'`): 網絡存取模式。'ISOLATED' 只允許連出互聯網；'PRIVATE' 會加入環境的私有網絡。 (Default: `'ISOLATED'`)

**env** (`Record<string, string>`): 內建於 Sandbox 並可供每個指令使用的環境變數。 (Default: `{}`)

**template** (`SandboxTemplate | (base: SandboxTemplate) => SandboxTemplate`): 從以 Railway template builder 建置的自訂基礎映像配置 Sandbox。接受 builder callback 或預先建置的 template。設定 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`): 底層 Railway Sandbox 實例，可直接存取 SDK。如 Sandbox 尚未啟動，會拋出 SandboxNotReadyError。

**processes** (`RailwayProcessManager`): 背景程序管理器。請參閱 SandboxProcessManager 參考。

## 方法

**fork** (`(options?) => Promise<RailwaySandbox>`): 將這個執行中的 Sandbox 複製為全新、獨立的 RailwaySandbox。傳回的 Sandbox 已經啟動，並已重新連接至 fork 出來的 Railway Sandbox。接受選用的 id、idleTimeoutMinutes、networkIsolation 及 env 覆寫值。如這個 Sandbox 尚未啟動，會拋出 SandboxNotReadyError。

**clone** (`(options?) => RailwaySandbox`): 建立一個尚未啟動、繼承憑證及預設值的同層 Sandbox。接受選用的 id、sandboxId、env、idleTimeoutMinutes 及 checkpointName 覆寫值。設定 options.checkpointName 時，複製的 Sandbox 會使用該值，否則會繼承 template 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/zh-HK/reference/workspace/process-manager)。

## Editor Provider

向 `MastraEditor` 註冊 Provider，以將已儲存的 Sandbox 設定載入為執行階段實例：

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

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

有關註冊自訂 Sandbox Provider 的詳情，請參閱 [Sandbox Provider 參考](https://mastra.zisheng.pro/zh-HK/reference/editor/sandbox-provider)。