Sandbox 실행 격리
Sandbox를 이용해 코드 실행, 파일 접근, 셸 실행, 브라우저 자동화를 격리하는 방법을 정리합니다.
툴을 가진 에이전트는 모델보다 위험합니다.
모델이 틀린 답을 내는 것은 품질 문제지만, 에이전트가 잘못된 코드나 명령을 실행하는 것은 보안 사고가 됩니다. 이때 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로 외부화되는가