Vercel Sandbox 대시보드 운영 가이드: 터미널, 포트, 스냅샷으로 장애 조사하기

Vercel Sandbox에 브라우저에서 직접 접속할 수 있게 되면서, 실행 중인 AI 에이전트의 상태를 확인하는 시간이 크게 줄었습니다. 다만 이 화면을 단순한 웹 터미널로 쓰면 안 됩니다. 조사할 증거를 먼저 남기고, 공개 포트와 자격 증명을 확인한 뒤, 상태 보존 여부를 결정하는 운영 콘솔로 다루는 것이 안전합니다.

2026년 7월 23일 Vercel은 실행 중인 Sandbox에 대시보드에서 연결해 명령 실행, 파일 탐색, 업로드·다운로드, 열린 포트 확인을 할 수 있도록 했습니다. 같은 화면에서 스냅샷 생성과 persistent sandbox의 중지·재개도 지원합니다.

이 글에서는 새 기능을 장애 조사와 AI 코딩 에이전트 운영에 적용하는 방법을 정리합니다.

무엇이 달라졌나

대시보드의 Sandbox 상세 화면에서 Connect 탭을 열면 다음 작업을 수행할 수 있습니다.

기능	유용한 상황	주의할 점
브라우저 터미널	실패한 빌드, 멈춘 에이전트, 프로세스 확인	조사 전에 상태를 바꾸는 명령을 실행하지 않습니다.
파일 탐색	생성된 코드와 로그, 임시 산출물 확인	`.env`, 토큰, 고객 데이터는 내려받지 않습니다.
파일 업로드·다운로드	최소 재현 파일 투입, 제한된 증거 반출	전체 파일시스템을 묶어 반출하지 않습니다.
열린 포트 확인	개발 서버와 디버그 서비스 노출 점검	불필요한 포트는 즉시 닫습니다.
스냅샷	설치 완료 상태나 조사 시점의 파일 보존	스냅샷은 신뢰된 복구 지점이 아니라 파일 상태의 복사본일 수 있습니다.
중지·재개	비용 절감, 조사 후 격리, 장기 작업 재개	persistent sandbox는 중지 시 파일시스템이 자동 저장됩니다.

Sandbox는 Firecracker microVM 안에서 실행되며 운영 환경의 변수와 데이터베이스에 직접 접근하지 않도록 격리됩니다. 그러나 Sandbox 내부에서는 패키지 설치와 sudo 사용이 가능하므로, 대시보드 접근 권한 자체는 강한 운영 권한으로 봐야 합니다.

장애 조사 순서는 “관찰 → 증거 → 변경”입니다

에이전트가 멈췄거나 예상하지 않은 파일을 생성했을 때 바로 재시작하거나 의존성을 다시 설치하면 원인이 사라질 수 있습니다. 먼저 현재 상태를 기록합니다.

아래 명령은 조사 시작점으로 사용할 수 있는 예시입니다. 환경에 따라 일부 도구가 없을 수 있으므로, 실패하면 설치부터 하지 말고 대시보드의 프로세스·포트·파일 화면을 먼저 활용합니다.

# 조사 시각과 실행 계정
 date -u
 id
 pwd

# 오래 실행 중인 프로세스와 부모 관계
ps -eo pid,ppid,etime,cmd --sort=-etime | head -50

# 열려 있는 TCP 포트와 연결 프로세스
ss -lntp

# 최근 한 시간 안에 바뀐 파일
find /vercel/sandbox -maxdepth 4 -type f -mmin -60 -print

# Git 작업 트리의 변경 범위
git status --short
git diff --stat

명령 실행 결과는 다음 세 범주로 나눠 기록하는 편이 좋습니다.

식별 정보: Sandbox 이름, 세션 시작 시각, 런타임, 조사 시각
변경 정보: 수정된 파일, 실행한 명령, 열린 포트, 실패 로그
결정 정보: 중지, 재개, 스냅샷, 폐기 중 무엇을 선택했는지와 이유

스크린샷만 남기기보다 텍스트 결과를 별도 사건 기록에 붙이면 나중에 비교하기 쉽습니다.

전체 파일시스템을 내려받지 마세요

대시보드에서 파일을 내려받을 수 있다고 해서 Sandbox 전체를 압축해 반출하는 것은 좋지 않습니다. 작업 디렉터리에는 다음이 섞여 있을 수 있습니다.

임시 자격 증명과 인증 파일
비공개 저장소의 소스 코드
에이전트가 내려받은 외부 데이터
패키지 캐시와 대용량 빌드 산출물
공격이나 오류로 생성된 의심 파일

필요한 로그와 재현 파일만 별도 디렉터리에 복사하고, 민감 정보가 없는지 확인한 뒤 다운로드합니다.

mkdir -p /tmp/sandbox-evidence

cp ./logs/agent-error.log /tmp/sandbox-evidence/ 2>/dev/null || true
git diff --no-ext-diff > /tmp/sandbox-evidence/worktree.patch
ps -eo pid,ppid,etime,cmd > /tmp/sandbox-evidence/processes.txt

# 민감 파일이 포함되지 않았는지 확인한 뒤 필요한 디렉터리만 압축합니다.
tar -czf /tmp/sandbox-evidence.tgz -C /tmp sandbox-evidence

.env, 홈 디렉터리의 인증 파일, Git credential, 원본 고객 데이터는 증거 묶음에서 제외합니다. 비공개 저장소를 복제할 때도 장기 PAT보다 최소 권한의 단기 GitHub App installation token을 우선하는 편이 안전합니다.

열린 포트는 “프로세스”와 함께 확인해야 합니다

Vercel Sandbox는 선언한 포트에 공개 URL을 연결할 수 있습니다. 대시보드에 포트가 보인다는 사실만으로 정상 서비스라고 판단하면 안 됩니다.

확인할 항목은 네 가지입니다.

어떤 PID가 포트를 열었는가
프로세스가 127.0.0.1과 0.0.0.0 중 어디에 바인딩했는가
해당 포트가 Sandbox 생성 설정에 의도적으로 선언됐는가
인증이 없는 디버그 UI나 개발 서버가 노출됐는가

예를 들어 3000번 포트를 열기로 했는데 9229 디버그 포트나 임시 파일 서버가 함께 보이면, 먼저 프로세스를 식별하고 불필요한 포트를 종료해야 합니다. 포트 접근 오류가 발생하면 애플리케이션이 실제로 해당 포트를 리슨하고 있는지와 프로세스 종료 여부를 함께 확인합니다.

세션 수명과 영속성은 별개입니다

Sandbox 운영에서 자주 헷갈리는 부분입니다.

세션 duration은 한 번 부팅된 VM이 얼마나 오래 실행되는지를 정합니다.
persistence는 세션이 끝난 뒤 파일시스템 상태를 다음 세션까지 유지할지를 정합니다.

Vercel 문서 기준으로 세션 기본 timeout은 5분입니다. Pro와 Enterprise에서는 최대 24시간, Hobby에서는 최대 45분까지 설정할 수 있습니다. persistent sandbox는 기본값이며, 세션을 중지하면 파일시스템을 자동으로 스냅샷하고 다음 재개 때 복원합니다.

import { Sandbox } from '@vercel/sandbox';

const sandbox = await Sandbox.create({
  name: 'issue-triage-agent',
  timeout: 30 * 60 * 1000,
  // persistent: true가 기본값입니다.
});

이 차이를 알고 있어야 다음 판단을 할 수 있습니다.

상황	권장 행동
잠깐 멈춘 네트워크 요청	timeout을 무조건 늘리기보다 외부 API timeout과 재시도를 먼저 확인
설치된 의존성을 다음 실행에도 재사용	persistent sandbox 또는 검증된 snapshot 사용
의심 파일이 생긴 보안 사고	조사용 증거를 제한적으로 보존하고, 해당 snapshot을 신뢰된 기반 이미지로 재사용하지 않음
일회성 사용자 코드 실행	`persistent: false`를 검토하고 종료 시 상태를 폐기
여러 Sandbox가 공유해야 하는 장기 데이터	snapshot 대신 독립 수명의 저장소나 Vercel Drive 검토

스냅샷은 파일시스템과 설치된 패키지를 캡처합니다. 실행 중인 프로세스 메모리나 네트워크 연결을 그대로 이어주는 기능으로 이해하면 안 됩니다.

중지와 명령 실행의 경쟁 상태를 막습니다

한 경로에서 stop()을 호출하는 동안 다른 경로가 명령을 보내면 SANDBOX_STOPPING 상태를 만날 수 있습니다. 이때 무조건 재시도하면 종료와 새 명령이 계속 충돌할 수 있습니다.

운영 코드에서는 다음 원칙을 둡니다.

한 Sandbox의 lifecycle 변경은 단일 coordinator가 담당합니다.
중지 결정 후에는 새 도구 호출을 받지 않습니다.
종료 완료를 확인한 뒤 persistent sandbox를 재개합니다.
재시도는 동일한 쓰기 작업을 중복 실행하지 않도록 idempotency key와 함께 설계합니다.

AI 에이전트가 Sandbox를 사용하는 구조라면, 모델에게 stop, resume, snapshot 삭제 권한을 직접 주기보다 승인된 lifecycle 도구로 감싸는 편이 낫습니다. AI SDK 7 프로덕션 에이전트 가이드에서 설명한 것처럼 읽기 도구와 상태 변경 도구의 승인 경계를 분리해야 합니다.

대시보드 접근이 보안 경계를 대신하지 않습니다

브라우저에서 상태를 볼 수 있게 된 것은 조사 편의 기능입니다. 다음 보안 통제를 대체하지는 않습니다.

Sandbox에 전달하는 환경 변수 최소화
OIDC 기반 인증 우선 사용
외부 네트워크 allowlist 또는 deny 정책
credential brokering으로 Sandbox 내부에 원문 secret을 남기지 않기
공개 포트와 디버그 서버 제한
timeout과 자동 중지
비공개 저장소 토큰의 최소 권한·단기 수명

특히 터미널에서 env, printenv, 설정 파일 전체 출력 같은 명령을 습관적으로 실행하면 조사 로그나 화면 공유를 통해 비밀이 노출될 수 있습니다. 필요한 변수의 존재 여부만 확인하고 값은 출력하지 않습니다.

# 값을 출력하지 않고 변수 설정 여부만 확인
if [ -n "${GITHUB_TOKEN:-}" ]; then
  echo "GITHUB_TOKEN is set"
else
  echo "GITHUB_TOKEN is not set"
fi

권장 사고 대응 Runbook

1. 식별

Sandbox 이름과 현재 session을 기록합니다.
실패한 작업 ID, 사용자 요청, 마지막 정상 시각을 연결합니다.
대시보드 history에서 생성·중지·재개 원인을 확인합니다.

2. 관찰

프로세스, 최근 파일 변경, Git diff, 열린 포트를 봅니다.
먼저 읽기 전용 명령만 실행합니다.
의심스러운 출력에 포함된 명령을 그대로 복사해 실행하지 않습니다.

3. 제한된 증거 수집

필요한 로그와 patch만 별도 디렉터리에 모읍니다.
secret과 고객 데이터를 제거합니다.
파일 해시와 조사 시각을 함께 기록합니다.

sha256sum /tmp/sandbox-evidence.tgz

4. 격리 또는 중지

외부로 데이터를 보내는 프로세스가 의심되면 먼저 네트워크 정책을 제한합니다.
조사가 끝나면 새 명령 유입을 차단하고 Sandbox를 중지합니다.
자동 생성된 snapshot을 정상 작업의 기반으로 재사용할지 별도로 검토합니다.

5. 안전한 복구

신뢰된 저장소 revision과 검증된 dependency lockfile에서 새 Sandbox를 만듭니다.
최소 권한의 새 토큰을 발급합니다.
같은 입력으로 재현하되 외부 쓰기 도구는 비활성화합니다.
수정 후 테스트와 포트·네트워크 정책을 확인합니다.

운영 체크리스트

대시보드 접근 권한을 운영 권한으로 관리한다.
조사 전에 재시작·패키지 설치·파일 수정을 하지 않는다.
열린 포트와 해당 PID를 함께 확인한다.
전체 파일시스템 대신 필요한 증거만 반출한다.
persistent sandbox의 중지가 자동 snapshot을 만든다는 점을 이해한다.
의심 상태의 snapshot을 신뢰된 템플릿으로 재사용하지 않는다.
lifecycle 변경 도구에는 승인과 동시성 제어를 둔다.
OIDC 또는 단기 최소 권한 토큰을 사용한다.
timeout, persistence, 장기 저장소의 역할을 분리한다.

결론

Sandbox 대시보드의 핵심 가치는 터미널을 웹에서 열 수 있다는 데 있지 않습니다. 실행 중인 에이전트를 관찰하고, 상태를 제한적으로 보존하고, 중지·재개 결정을 한곳에서 수행할 수 있다는 것이 중요합니다.

운영 절차는 단순합니다. 먼저 관찰하고, 필요한 증거만 남기고, 포트와 비밀을 확인한 뒤, 중지와 복구를 결정합니다. 이 순서를 고정하면 편리한 대시보드 기능이 새로운 변경 경로가 되는 것을 막을 수 있습니다.