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

# 철도샌드박스

일시적이고 격리된 명령을 실행합니다.[Railway](https://docs.railway.com/sandboxes)샌드박스. 각 샌드박스는 Railway TypeScript SDK를 통해 요청 시 프로비저닝되는 격리된 Debian Linux VM입니다. 스트리밍 출력, 명령 시간 제한, 구성 가능한 유휴 시간 제한을 통해 명령 실행을 지원합니다.`ISOLATED`/`PRIVATE`네트워크 격리, 철도 템플릿 빌더를 통한 사용자 정의 기본 이미지, 체크포인트 지원 복구, 실행 중인 샌드박스 포크, ID로 기존 샌드박스에 다시 연결 등이 있습니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/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
```

세 가지 방법 중 하나로 철도 자격 증명을 설정하세요.

**Shell export**:

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

**.env file**:

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

**Constructor**:

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

### 비공개 네트워킹

다른 철도 서비스에 연결하려면 해당 환경의 개인 네트워크에 가입하세요(예:`postgres.railway.internal`):

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

기본 `ISOLATED` 모드에서는 아웃바운드 인터넷 액세스만 허용되며 사설 네트워크에는 연결할 수 없습니다.

### 사용자 정의 기본 이미지(템플릿)

모든 샌드박스가 준비될 수 있도록 패키지를 사전 설치하고 설정 단계를 실행하세요. 철도 템플릿 빌더를 통해 빌더 콜백을 전달합니다. 템플릿은 첫 번째 템플릿에서 한 번 생성됩니다.`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의 파일 시스템에 다시 연결하므로 템플릿이 무시됩니다.

### 실행 중인 샌드박스 포크

실행 중인 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()` options.

### 체크포인트 복구

Railway Sandbox 교체 시에도 Sandbox 파일 시스템을 유지하려면 `checkpointName`을 설정합니다. `start()`를 호출하면 `RailwaySandbox`가 먼저 체크포인트에서 Sandbox 생성을 시도합니다. 체크포인트가 없으면 구성된 템플릿 또는 기본 이미지에서 Sandbox를 생성한 후 체크포인트를 캡처합니다.

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

`RailwaySandbox`유휴 시간 초과 직전에 체크포인트를 새로 고칩니다. 복구는 최근에 성공한 체크포인트를 복원합니다. 마지막 체크포인트 이후 실행 중인 프로세스나 파일 시스템 쓰기는 복원하지 않습니다.

각 독립 파일 시스템에 대해 하나의 안정적인 체크포인트 이름을 사용합니다. 관련되지 않은 세션이나 프로젝트 간에 체크포인트 이름을 공유하지 마세요.

### 복제된 샌드박스 체크포인트

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

두 콜백 모두 선택 사항이며 독립적으로 사용할 수 있습니다.

### 기존 샌드박스에 다시 연결

철도 샌드박스는 이를 생성한 프로세스보다 오래 지속됩니다. 새 ID를 프로비저닝하는 대신 철도 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: `자동 생성`)

**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의 초기 상태를 제공하고 유휴 상태로 해제되기 전에 파일 시스템을 보존하는 데 사용하는, 이름이 지정된 Railway 체크포인트입니다. 각 독립 파일 시스템에 고유하고 안정적인 이름을 사용하세요.

**idleTimeoutMinutes** (`number`): Railway가 Sandbox를 자동으로 제거하기 전까지 실행 상호작용 없이 유휴 상태로 둘 수 있는 시간입니다. 유효한 범위와 기본값은 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`백그라운드 프로세스 생성 및 관리를 위한 내장 프로세스 관리자가 포함되어 있습니다. 생성된 각 프로세스는 철도로 실행됩니다.`exec` session.

```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()
```

철도의`exec` API doesn't stream stdin, so `sendStdin()` isn't supported.

전체 API는 [`SandboxProcessManager` 레퍼런스](https://mastra.zisheng.pro/ko/reference/workspace/process-manager)를 참조하세요.

## 편집자 Provider

저장된 Sandbox 구성을 런타임 인스턴스로 변환하도록 `MastraEditor`에 Provider를 등록합니다.

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

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

사용자 지정 Sandbox Provider 등록에 관한 자세한 내용은 [Sandbox Provider 레퍼런스](https://mastra.zisheng.pro/ko/reference/editor/sandbox-provider)를 참조하세요.