Vercel샌드박스
내부에서 명령을 실행합니다.Vercel Sandbox그건 임시적이야폭죽Amazon Linux 2023을 실행하는 MicroVM. 지속적인 세션 내 파일 시스템을 제공합니다.sudo액세스, 노출된 포트 및 백그라운드 프로세스. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceSandbox 인터페이스.
이는 명령을 상태 비저장 Vercel 서버리스 Functions로 실행하는 VercelServerlessSandbox와 다릅니다. VercelSandbox는 영구 파일 시스템과 장기 실행 프로세스를 갖춘 전체 Linux MicroVM을 실행합니다.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/vercel
pnpm add @mastra/vercel
yarn add @mastra/vercel
bun add @mastra/vercel
입증입증에 대한 직접 링크
명시적인 자격 증명을 제공하지 않으면 @vercel/sandbox SDK가 Vercel OIDC 토큰을 자동으로 사용합니다. token, teamId, projectId 중 하나를 제공하는 경우 세 값을 모두 함께 제공하세요.
- OIDC (recommended)
- Access token (.env)
- Constructor
로컬 개발의 경우 프로젝트를 연결하고 개발 토큰을 가져옵니다.
vercel link
vercel env pull
Vercel에서는 인증이 자동으로 처리되므로 구성이 필요하지 않습니다.
OIDC가 없는 환경의 경우 세 가지 값을 모두 함께 제공합니다.
VERCEL_TOKEN=your-token
VERCEL_TEAM_ID=your-team-id
VERCEL_PROJECT_ID=your-project-id
new VercelSandbox({
token: 'your-token',
teamId: 'your-team-id',
projectId: 'your-project-id',
})
용법용법에 대한 직접 링크
Workspace에 VercelSandbox를 추가하고 Agent에 할당합니다.
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelSandbox } from '@mastra/vercel'
const workspace = new Workspace({
sandbox: new VercelSandbox({
runtime: 'node24',
timeout: 600_000,
}),
})
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 Node.js version.')
console.log(response.text)
리소스 및 노출된 포트리소스 및 노출된 포트에 대한 직접 링크
vCPU(vCPU당 Memory 2048MB)를 할당하고 포트를 노출하여 샌드박스 내부에서 실행되는 네트워크 서비스에 연결합니다.
const sandbox = new VercelSandbox({
runtime: 'node24',
resources: { vcpus: 4 },
ports: [3000],
})
const workspace = new Workspace({ sandbox })
await sandbox.start()
// The public HTTPS domain for an exposed port is available via getInfo()
const { metadata } = sandbox.getInfo()
console.log(metadata?.domains) // { 3000: 'https://....vercel.run' }
스트리밍 출력스트리밍 출력에 대한 직접 링크
onStdout 및 onStderr 콜백을 통해 명령 출력을 실시간으로 스트리밍합니다.
await sandbox.executeCommand('sh', ['-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?:
sandboxName?:
token?:
teamId?:
projectId?:
runtime?:
timeout?:
resources?:
ports?:
env?:
metadata?:
instructions?:
onStart?:
running 상태에 도달한 후 호출되는 수명 주기 훅입니다.onStop?:
onDestroy?:
속성속성에 대한 직접 링크
id:
name:
provider:
status:
sandbox:
processes:
백그라운드 프로세스백그라운드 프로세스에 대한 직접 링크
VercelSandbox백그라운드 프로세스를 생성하고 관리하기 위한 프로세스 관리자가 포함되어 있습니다. 생성된 각 프로세스는 MicroVM 내에서 분리된 명령으로 실행되며 출력은 명령 로그를 통해 스트리밍됩니다.
const sandbox = new VercelSandbox({ runtime: 'node24', ports: [3000] })
await sandbox.start()
const handle = await sandbox.processes.spawn('node server.js', {
env: { PORT: '3000' },
onStdout: data => console.log(data),
})
console.log(handle.stdout)
await handle.kill()
전체 API는 SandboxProcessManager 레퍼런스를 참조하세요.
Vercel Sandbox SDK는 명령 실행을 위한 stdin 채널을 노출하지 않으므로 handle.sendStdin()은 오류를 발생시킵니다. 이 Provider는 파일 시스템 마운트(FUSE)도 지원하지 않습니다.
제한제한에 대한 직접 링크
- vCPU당 Memory가 2048MB인 최대 32개의 vCPU.
- 최대 15개의 노출된 포트.
- 파일 시스템은 임시적입니다. 세션 내에서만 지속되며 샌드박스가 중지되면 손실됩니다.
- 최대 실행 시간은 계획에 따라 다르며(Hobby에서는 45분, Pro 및 Enterprise에서는 최대 24시간) 기본값은 5분입니다.
현재 제한 사항과 가격은 Vercel Sandbox 문서를 참조하세요.