코드 샌드박스 · 도움말 · Onpod

샌드박스는 코딩 에이전트나 API가 만드는 임시 격리 실행 환경이에요 (sbx-*). 사용자 레포를 클론해 테스트·빌드·실행하거나, 신뢰할 수 없는 코드를 안전하게 실행할 때 써요. 만든 뒤 TTL(수명)이 지나면 자동으로 삭제되고, 실행 중인 시간만큼 초당 과금돼요. 공개 URL은 없어요.

사람이 콘솔/CLI로 “배포”하는 앱과는 다른 종류라, 앱 목록·팟 목록·콘솔 「내 팟」에는 섞여 나오지 않아요 (에이전트가 여러 개 띄워도 실제 앱을 가리지 않도록 분리). 생성은 코딩 에이전트나 API가 하고, 사람은 보기·종료만하면 돼요.

코딩 에이전트한테 이렇게 말하세요

“이 레포 샌드박스에 클론해서 테스트 돌려보고 결과 알려줘”

“onpod 샌드박스 하나 띄워서 이 스크립트 실행해줘. 끝나면 정리하고”

사람이 하는 일 — 보기·종료만

콘솔 왼쪽 「샌드박스」 메뉴에서 지금 실행 중인 샌드박스 목록, 남은 TTL, 시간당 요금을 볼 수 있어요. 생성 버튼은 일부러 없어요(역할 분리). 비용이 걱정되거나 잊고 실행 중인 게 보이면 거기서 즉시 종료(kill) 하면 돼요. CLI 로도 같은 일을 할 수 있어요:

onpod sandbox ls            # 실행 중인 샌드박스 + 남은 TTL·시간당 요금 (--json)
onpod sandbox rm <id>       # 샌드박스 즉시 종료 + 완전 삭제 (한 번이면 과금 끝)

AI 에이전트 · 개발자용 — /v1/sandboxes REST API

샌드박스 생성은 API 로만 해요(CLI 에는 생성 명령이 없어요). 코딩 에이전트나 직접 만든 프로그램이 API 토큰으로 호출하면 돼요. 전체 계약은 공개 OpenAPI 스펙(/v1/openapi.json)과 onpod manual 에도 있어요.

POST   /v1/sandboxes              생성. body {image, class(nano|micro(기본)|small|medium), ttl_secs, egress_allowlist[], env{}, labels{}}
                                  → {id, state:"creating", ...}  보통 수 초 안에 running (warm 풀)
GET    /v1/sandboxes              내 샌드박스 목록 (state·class·expires_at·hourly_rate_microusd)
GET    /v1/sandboxes/{id}         상태 폴링 (state=running 되면 사용 가능)
POST   /v1/sandboxes/{id}/exec    명령 실행. body {cmd:["sh","-c","..."], timeout_secs}
                                  → {state, result:{stdout, stderr, exit_code, truncated}}   (출력 1 MiB/스트림 상한)
GET    /v1/sandboxes/{id}/exec-stream   WebSocket. 긴 명령 실시간 스트림 + {"t":"exit","code":N}
POST   /v1/sandboxes/{id}/files   파일 쓰기. body {files:[{path, content | content_b64}]}
GET    /v1/sandboxes/{id}/files?path=   파일 읽기 (base64)
DELETE /v1/sandboxes/{id}         즉시 종료 + 완전 삭제 → {state, purge:true}. 한 번이면 끝(멈춘 상태로 남아 디스크 요금이 나가지 않아요 · TTL 만료도 같음)

호출에는 sandboxes:read / sandboxes:write 스코프가 있는 API 키가 필요해요. 키는 /api-keys 에서 최소권한 스코프로 발급하세요.

클래스 · 요금

클래스는 자원 크기예요. 실행 중인 시간만큼 초당 과금되고, TTL이 지나거나 종료하면 멈춰요. 정확한 단가는 /pricing 에서 확인하세요.

class	용도
nano	아주 짧은 명령·린트·빠른 확인
micro (기본)	가벼운 스크립트·단위 테스트·간단한 빌드
small / medium	무거운 빌드·통합 테스트·여러 프로세스

격리 · 보안 (꼭 읽어주세요)

유저별 완전 격리 컨테이너 + 격리 디스크. 작업이 끝나면 TTL로 자동 삭제돼요.
egress_allowlist(도메인·IP 대역)를 주면 목록 밖으로 나가는 통신을 기본 차단해요. 정확한 도메인(예: api.github.com)이나 IP/CIDR만 되고, 와일드카드는 안 돼요(만들 때 바로 알려줘요). 응답의 egress_enforced 가 true 면 차단이 적용된 거예요(도입 전에 만든 샌드박스는 기록만 남아 있어요). 차단을 켰어도 시크릿은 넣지 않는 쪽(아래 참고)이 우선이에요.
🔴 LLM 키·깃 토큰 같은 장수명 시크릿을 샌드박스에 주입하지 마세요. 샌드박스 안 코드는 신뢰할 수 없는 것으로 봐야 해요. 키는 호스트(에이전트 두뇌)가 들고 LLM·깃 호출을 대신하고, 꼭 필요하면 단기·레포 한정 토큰만 그때그때 주입하세요 (brain-on-host 패턴).