Sandbox 실행 격리
Sandbox를 이용해 코드 실행, 파일 접근, 셸 실행, 브라우저 자동화를 격리하는 방법을 정리합니다.
핵심 요약
- 파일·셸·코드·브라우저를 다루는 tool의 기본값은 Sandbox입니다. 성능이 아니라 피해 반경을 제한하는 격리 경계이기 때문입니다.
- 권한 모델은 파일시스템을 작업 디렉터리로, 네트워크를 allowlist로, 명령을 허용된 도구로 제한하고 수명을 짧게 가져갑니다.
- AI SDK tool과 Sandbox를 결합할 때는 MicroVM에서 updateNetworkPolicy로 허용 도메인을 지정하고, 결과물은 artifact로 빼냅니다.
- prompt injection을 완전히 막는다고 가정하지 말고, 침해되더라도 갈 수 있는 범위를 좁히는 방어 전략을 택합니다.
- snapshot은 blank/language/task-specific 중에서 재현성과 성능을 저울질해 고르고, 템플릿 sprawl을 경계합니다.
툴을 쥔 에이전트는 모델보다 위험합니다.
모델이 틀린 답을 내면 품질 문제지만, 에이전트가 잘못된 코드나 명령을 실행하면 보안 사고가 됩니다. 이때 Sandbox는 성능 최적화 기능이 아니라 격리 경계입니다.
왜 Sandbox가 필요한가
| 시나리오 | Sandbox 없이 발생하는 문제 | Sandbox가 줄이는 위험 |
|---|---|---|
| 코드 생성 후 실행 | 앱 인프라 오염 | 실행 환경 격리 |
| 파일 읽기/쓰기 | 민감 파일 노출 | 파일시스템 범위 제한 |
| 브라우저 자동화 | 세션 탈취, 외부 이동 | 네트워크 정책화 |
| 셸 명령 실행 | lateral movement | untrusted runtime 격리 |
격리 구조
권한 모델
| 권한 축 | 기본값 | 이유 |
|---|---|---|
| 파일시스템 | 작업 디렉터리만 | 시스템 파일 보호 |
| 네트워크 | allowlist only | 데이터 유출 억제 |
| 명령 | 허용된 도구만 | shell breakout 완화 |
| 수명 | 짧게 | 장기 침투 방지 |
| snapshot | 재현 가능한 템플릿만 | drift 감소 |
AI SDK tool과 Sandbox 결합 패턴
import { tool } from 'ai'
import { Sandbox } from '@vercel/sandbox'
import { z } from 'zod'
export const runAnalysis = tool({
description: '격리된 환경에서 분석 스크립트를 실행합니다.',
inputSchema: z.object({
repo: z.string().url(),
task: z.string(),
}),
execute: async ({ repo, task }) => {
const sandbox = await Sandbox.create({
runtime: 'node24',
name: 'analysis-worker',
tags: { env: 'preview', purpose: 'agent-analysis' },
})
await sandbox.updateNetworkPolicy({ allow: ['github.com', 'api.github.com'] })
await sandbox.runCommand('git', ['clone', repo, '/vercel/sandbox/repo'])
const result = await sandbox.runCommand('node', [
'/vercel/sandbox/repo/scripts/run-task.js',
task,
])
return result.stdout()
},
})운영 태그
Sandbox custom tags는 2026년 4월 말 기준 beta 기능입니다. 팀 단위로 sandbox가 늘어나면 env, team, tenant, agentRunId 같은 태그를 붙여 비용·정리·감사 대상을 빠르게 찾습니다.
| 태그 | 목적 |
|---|---|
env | preview/staging/production 구분 |
team | 비용 책임과 운영 담당자 추적 |
tenant | 멀티테넌트 격리·정산 |
agentRunId | 에이전트 실행 로그와 sandbox 연결 |
Snapshot 전략
| 전략 | 장점 | 주의점 |
|---|---|---|
| blank image | 가장 안전 | 초기화 비용 증가 |
| language template snapshot | 빠른 시작 | 패키지 drift 관리 필요 |
| task-specific snapshot | 성능 최적화 | 템플릿 sprawl 주의 |
실무 해석
prompt injection을 완전히 막는다고 가정하지 않는 편이 안전합니다. 대신 Sandbox로 "툴이 침해되더라도 어디까지 갈 수 있는가"를 제한하는 쪽이 현실적인 방어 전략입니다.
운영 규칙
- 파일/셸/브라우저가 등장하면 기본값은 Sandbox입니다.
- 쓰기 가능한 볼륨은 최소로 줄이고, 결과물은 artifact로 빼냅니다.
- 재현성이 필요한 작업은 snapshot을 버전으로 관리합니다.
- Sandbox policy 변경은 애플리케이션 배포와 분리해 검토합니다.
ADR 스타일 결론
Decision
파일, 코드, 셸, 브라우저를 다루는 tool은 기본적으로 Sandbox에서 실행합니다. Sandbox는 편의 기능이 아니라 에이전트의 피해 반경을 제한하는 격리 경계입니다.
실무 체크리스트
- Sandbox 없이 실행되는 shell/file tool이 남아 있지 않은가
- 네트워크 정책이 allowlist 기반으로 제한되는가
- snapshot이 템플릿 버전으로 관리되는가
- 결과물이 로컬 디스크가 아니라 artifact로 외부화되는가