철도샌드박스
일시적이고 격리된 명령을 실행합니다.Railway샌드박스. 각 샌드박스는 Railway TypeScript SDK를 통해 요청 시 프로비저닝되는 격리된 Debian Linux VM입니다. 스트리밍 출력, 명령 시간 제한, 구성 가능한 유휴 시간 제한을 통해 명령 실행을 지원합니다.ISOLATED/PRIVATE네트워크 격리, 철도 템플릿 빌더를 통한 사용자 정의 기본 이미지, 체크포인트 지원 복구, 실행 중인 샌드박스 포크, ID로 기존 샌드박스에 다시 연결 등이 있습니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox 인터페이스.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/railway
pnpm add @mastra/railway
yarn add @mastra/railway
bun add @mastra/railway
세 가지 방법 중 하나로 철도 자격 증명을 설정하세요.
- Shell export
- .env file
- Constructor
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)
비공개 네트워킹비공개 네트워킹에 대한 직접 링크
다른 철도 서비스에 연결하려면 해당 환경의 개인 네트워크에 가입하세요(예:postgres.railway.internal):
const workspace = new Workspace({
sandbox: new RailwaySandbox({
networkIsolation: 'PRIVATE',
env: { NODE_ENV: 'production' },
}),
})
기본 ISOLATED 모드에서는 아웃바운드 인터넷 액세스만 허용되며 사설 네트워크에는 연결할 수 없습니다.
사용자 정의 기본 이미지(템플릿)사용자 정의 기본 이미지(템플릿)에 대한 직접 링크
모든 샌드박스가 준비될 수 있도록 패키지를 사전 설치하고 설정 단계를 실행하세요. 철도 템플릿 빌더를 통해 빌더 콜백을 전달합니다. 템플릿은 첫 번째 템플릿에서 한 번 생성됩니다.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의 파일 시스템에 다시 연결하므로 템플릿이 무시됩니다.
실행 중인 샌드박스 포크실행 중인 샌드박스 포크에 대한 직접 링크
실행 중인 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() options.
체크포인트 복구체크포인트 복구에 대한 직접 링크
Railway Sandbox 교체 시에도 Sandbox 파일 시스템을 유지하려면 checkpointName을 설정합니다. start()를 호출하면 RailwaySandbox가 먼저 체크포인트에서 Sandbox 생성을 시도합니다. 체크포인트가 없으면 구성된 템플릿 또는 기본 이미지에서 Sandbox를 생성한 후 체크포인트를 캡처합니다.
const sandbox = new RailwaySandbox({
checkpointName: 'project-session-42',
idleTimeoutMinutes: 30,
})
RailwaySandbox유휴 시간 초과 직전에 체크포인트를 새로 고칩니다. 복구는 최근에 성공한 체크포인트를 복원합니다. 마지막 체크포인트 이후 실행 중인 프로세스나 파일 시스템 쓰기는 복원하지 않습니다.
각 독립 파일 시스템에 대해 하나의 안정적인 체크포인트 이름을 사용합니다. 관련되지 않은 세션이나 프로젝트 간에 체크포인트 이름을 공유하지 마세요.
복제된 샌드박스 체크포인트복제된 샌드박스 체크포인트에 대한 직접 링크
구성된 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),
})
두 콜백 모두 선택 사항이며 독립적으로 사용할 수 있습니다.
기존 샌드박스에 다시 연결기존 샌드박스에 다시 연결에 대한 직접 링크
철도 샌드박스는 이를 생성한 프로세스보다 오래 지속됩니다. 새 ID를 프로비저닝하는 대신 철도 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백그라운드 프로세스 생성 및 관리를 위한 내장 프로세스 관리자가 포함되어 있습니다. 생성된 각 프로세스는 철도로 실행됩니다.exec session.
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 레퍼런스를 참조하세요.
편집자 Provider편집자 Provider에 대한 직접 링크
저장된 Sandbox 구성을 런타임 인스턴스로 변환하도록 MastraEditor에 Provider를 등록합니다.
import { railwaySandboxProvider } from '@mastra/railway'
const editor = new MastraEditor({
sandboxes: { [railwaySandboxProvider.id]: railwaySandboxProvider },
})
사용자 지정 Sandbox Provider 등록에 관한 자세한 내용은 Sandbox Provider 레퍼런스를 참조하세요.