클라우드 샌드박스 사용하기

클라우드 샌드박스 사용하기 (Use cloud sandboxes)

지원되는 sbx 명령에 --cloud 플래그를 붙여 클라우드 샌드박스를 만들고 관리하는 방법을 알아볼게요.

출처: 문서

본문

지원되는 sbx 명령에 --cloud 플래그를 사용해 Docker 관리 인프라에서 샌드박스를 만들고 관리해요. 클라우드 작업은 로컬 샌드박스 데몬 대신 클라우드 ID, 이름, 리소스, 수명 주기 제어를 사용해요.

샌드박스 만들기 (Create a sandbox)

클라우드 샌드박스는 기본적으로 1시간 후에 만료돼요. 만료되면 서비스가 재개 가능한 샌드박스를 멈추고 나머지를 삭제해요. 만들기 전에 타임아웃과 동작을 선택하려면 Configure expiration을 보세요.

로컬 샌드박스용으로 저장한 자격 증명은 클라우드 샌드박스에서 쓸 수 없어요. 에이전트를 실행하기 전에 클라우드 자격 증명을 구성하세요.

샌드박스를 만들고 그 에이전트에 붙거나, 이미 있으면 이름 있는 샌드박스를 재사용해요:

$ sbx --cloud run claude --name cloud-project

--name이 없으면 대화형 run이 그 에이전트의 기존 샌드박스들과 새로 만들기 옵션을 보여줘요. --new를 전달해 새로운 샌드박스를 만들어요. 키트 템플릿을 굽는 실행도 새 샌드박스를 만들어요.

샌드박스 재사용은 생성 설정을 유지해요. --cpus, --memory, --platform, --ttl, --env, --allow-network 같은 플래그는 재개 시 거부돼요. 다른 설정의 샌드박스를 만들려면 --new를 사용하세요.

에이전트 세션을 열지 않고 샌드박스를 만들려면 create를 사용해요:

$ sbx --cloud create --name cloud-project claude

명령은 클라우드 샌드박스 ID를 출력해요. ID나 이름으로 붙어요:

$ sbx --cloud attach cloud-project

클라우드 샌드박스 이름은 최소 2자여야 하고, 문자나 숫자로 시작해야 하며, 문자·숫자·하이픈만 포함해야 해요. default 이름은 예약되어 있어요. 로컬 샌드박스 이름에 허용되는 마침표는 클라우드에서 허용되지 않아요.

클라우드 생성은 워크스페이스 경로를 받지 않아요. 예를 들어 sbx --cloud run claude .는 .이 로컬 파일시스템을 가리키므로 오류를 반환해요.

리소스와 플랫폼 선택하기 (Choose resources and platform)

리소스 플래그가 없으면 클라우드 샌드박스는 2 CPU와 4 GiB 메모리로 시작해요. --cpus와 --memory로 다음 구성 중 하나를 선택해요:

크기 (Size)	CPUs	메모리 (Memory)
micro	1	2 GiB
small	2	4 GiB
medium	4	8 GiB
large	8	16 GiB
xl	16	32 GiB

예를 들어:

$ sbx --cloud create --name cloud-project --cpus 4 --memory 8g claude

CPU나 메모리 하나만 지정하면 CLI가 다른 리소스의 일치하는 값을 선택해요. 지원되지 않는 조합은 거부돼요.

--platform linux/amd64 또는 --platform linux/arm64로 계정이 지원하는 아키텍처를 선택하세요. 샌드박스를 여러분의 머신으로 옮길 계획이라면 아키텍처가 일치해야 하므로 중요해요.

붙지 않고 실행하기 (Run without attaching)

스크립트나 대화형 입력이 없는 터미널에서는 에이전트 세션을 열지 않고 샌드박스를 시작해요:

$ sbx --cloud run --detached claude --name cloud-task

--name이 있는 분리 실행(detached run)은 이름 있는 샌드박스를 재사용하고 멈춰 있다면 시작해요. 샌드박스가 없거나 --name을 생략하면 새 샌드박스를 만들어요. 명령 실행은 sbx --cloud exec, 무인 정리는 sbx --cloud rm --force를 사용하세요. 대화형 에이전트 세션은 터미널에서의 run 또는 attach가 필요해요.

대화형 run·attach 세션에서 에이전트를 실행한 채로 분리하려면 Ctrl+\를 눌러요. sbx --cloud attach <sandbox-name>으로 다시 연결해요. 다시 연결하면 기존 에이전트 세션에 합류해요. run·attach에 --detach-keys를 써서 분리 제스처를 바꿀 수 있어요. 예를 들어 --detach-keys ctrl-x,ctrl-d.

샌드박스 나열하고 검사하기 (List and inspect sandboxes)

클라우드 샌드박스를 로컬 샌드박스와 별도로 나열해요:

$ sbx --cloud ls

대부분의 클라우드 명령은 샌드박스 이름이나 출력에 표시된 sbx_ 접두사 ID를 받아요.

명령 실행하기 (Run commands)

클라우드 샌드박스 안에서 명령을 실행해요:

$ sbx --cloud exec cloud-project pwd

SSH로 연결하기 (Connect with SSH)

클라우드 SSH 접근을 구성하고 SSH 클라이언트로 연결해요:

$ sbx --cloud setup ssh
$ ssh sbx_01abc123@sbx_cloud

예시를 ssh <sandbox-id>@sbx_cloud로 바꾸고, sbx --cloud ls의 sbx_ 접두사 ID를 사용하세요.

파일 전송하기 (Transfer files)

sbx --cloud cp로 클라이언트 머신과 클라우드 샌드박스 사이에서 파일이나 디렉터리를 복사해요. 샌드박스 절대 경로를 사용하세요:

$ sbx --cloud cp ./src cloud-project:/home/agent/workspace/src
$ sbx --cloud cp cloud-project:/home/agent/workspace/result.json ./result.json

복사는 특정 시점(point-in-time) 전송을 만들어요. 로컬 경로를 마운트하거나 동기화하지 않아요. 소스 제어 워크플로에서는 샌드박스 안에서 원격 저장소를 클론하고 원격으로 변경을 push 할 수도 있어요. 개인 저장소 접근이 필요한 샌드박스를 만들기 전에 클라우드 자격 증명을 구성하세요. 클라우드 연습(cloud walkthrough)이 공개 저장소 예시를 보여줘요.

포트 노출하기 (Expose a port)

샌드박스 포트를 지정해 TCP 서비스를 노출해요:

$ sbx --cloud ports cloud-project --publish 8080

명령은 클라우드 컨트롤 플레인이 할당한 공개 HTTPS URL을 반환해요. 클라우드 모드는 선택적 /tcp 접미사가 있는 샌드박스 포트 번호(예: 8080/tcp)를 받아요. 호스트 IP 주소, 호스트 포트 바인딩, 다른 프로토콜은 거부돼요.

노출된 포트를 나열하거나 제거해요:

$ sbx --cloud ports cloud-project
$ sbx --cloud ports cloud-project --unpublish 8080

노출된 URL은 공개 엔드포인트로 다뤄요. 서비스에 인증을 적용하고, 더 필요 없으면 노출을 제거하세요.

만료 구성하기 (Configure expiration)

생성 중 수명(time-to-live)과 만료 시 동작을 설정해요:

$ sbx --cloud create --name cloud-project --ttl 2h --on-timeout delete claude

기본 수명은 1시간이에요. --on-timeout을 생략하면 서버가 재개 가능한 샌드박스를 멈추고 나머지를 삭제해요. 특정 결과가 필요할 때는 동작을 명시적으로 선택하세요:

stop — 샌드박스를 보존해 다시 시작할 수 있게 해요. 샌드박스를 멈추는 지원이 필요해요.
restart — 샌드박스를 멈췄다가 즉시 다시 시작해요. --ttl도 지정한다면 최소 1시간이어야 해요.
delete — 샌드박스를 제거해요.

볼륨 기반 샌드박스는 delete 동작이 필요해요. --ttl을 생략하면 서버 기본값을 사용해요. --ttl 0을 설정하는 것은 오류로, 만료를 비활성화하는 방법이 아니에요.

만료를 검사하거나 연장해요. 연장은 생성 시점으로부터 24시간을 넘길 수 없어요:

$ sbx --cloud ttl cloud-project
$ sbx --cloud ttl +30m cloud-project

샌드박스 멈추거나 제거하기 (Stop or remove a sandbox)

메모리와 파일시스템을 보존하며 클라우드 샌드박스를 멈춰요:

$ sbx --cloud stop cloud-project

명령은 stop 요청이 받아들여지면 반환해요. sbx --cloud ls로 샌드박스가 멈췄는지 확인하세요. 멈춘 동안에는 컴퓨트가 과금되지 않아요.

샌드박스를 재개하고 에이전트에 연결하려면:

$ sbx --cloud attach cloud-project

sbx --cloud run claude --name cloud-project를 쓰거나, --name 없이 에이전트를 실행해 프롬프트에서 샌드박스를 선택할 수도 있어요. 이름 있는 run에 --detached를 추가해 붙지 않고 재개해요.

재개는 샌드박스 ID와 상태를 유지해요. 재개 후 sbx --cloud ttl cloud-project로 만료를 확인하세요.

stop이나 resume이 기존 샌드박스를 찾지 못했다고 보고하면, 그 작업이 계정에 대해 비활성화되어 있을 수 있어요.

볼륨 기반 샌드박스는 멈출 수 없어요. 볼륨 기반 샌드박스를 제거해 종료하고 볼륨 스냅샷을 저장하세요.

상태가 더 필요 없으면 샌드박스를 제거해요:

$ sbx --cloud rm cloud-project

제거는 확인을 요청하고, 클라우드 샌드박스를 삭제하며, 되돌릴 수 없어요. 스크립트에서 프롬프트를 건너뛰려면 --force를 사용하세요.

영구 볼륨 사용하기 (Use persistent volumes)

클라우드 볼륨은 실험적이고 샌드박스와 무관하게 데이터를 보존해요. 볼륨을 만든 뒤 샌드박스 생성 시 붙여요:

$ sbx --cloud volume create dependency-cache
$ sbx --cloud create --name cloud-project \
  --volume dependency-cache:/workspace/cache claude

새로 만든 볼륨의 루트 디렉터리는 root가 소유해요. 붙인 뒤 소유권을 바꿔 에이전트가 쓸 수 있게 해요:

$ sbx --cloud exec cloud-project \
  sudo chown agent:agent /workspace/cache

볼륨 데이터는 샌드박스가 나갈 때 스냅샷으로 저장되지, 연속적으로 저장되지 않아요. 여러 샌드박스가 같은 볼륨을 동시에 마운트하면, 마지막으로 나간 샌드박스가 저장된 스냅샷을 덮어써요.

클라우드 샌드박스 커스터마이즈하기 (Customize a cloud sandbox)

클라우드 템플릿은 자체 저장소가 있어요. 로컬 템플릿은 전송하기 전까지 sbx --cloud에서 쓸 수 없어요. 실행 중인 클라우드 샌드박스를 캡처하고 그 템플릿에서 다른 샌드박스를 만들려면:

$ sbx --cloud template save cloud-project cloud-template
$ sbx --cloud create --name cloud-copy --template cloud-template

템플릿은 CPU·메모리 구성을 제공해요. --template을 에이전트 이름, --cpus, --memory와 함께 쓰지 마세요. 대신 OCI 이미지를 직접 실행하려면 명시적 CPU·메모리 값과 함께 --image-ref를 사용하세요.

스냅샷은 샌드박스 파일시스템에 쓰인 자격 증명을 포함해요. 템플릿을 저장하기 전에 그 자격 증명을 제거하세요. 관리 클라우드 시크릿은 시크릿 저장소에 남아요. Authenticate cloud agents 문서를 보세요.

클라우드 샌드박스는 샌드박스 키트와 --kit 믹스인도 지원해요. 커스터마이즈는 Kits 문서, 호스트 의존 기능은 Local and cloud differences 문서를 보세요. 로컬 키트를 적용하기 전에 클라우드 자격 증명을 구성하세요.

재사용 가능한 클라우드 구성을 파일로 선언하려면 Use a cloud environment 문서를 보세요.

MCP 서버 로드하기 (Load an MCP server)

클라우드 샌드박스에 로드하기 전에 Docker Agentic Platform에서 MCP 서버를 연결하세요. sbx와 사용하는 같은 Docker 계정을 사용해요.

콘솔의 이름을 사용해 실행 중인 클라우드 샌드박스에 연결된 서버를 로드해요:

$ sbx --cloud mcp load <server-name> --sandbox cloud-project

서버 이름은 Docker Agentic Platform 계정과 연결된 MCP 게이트웨이가 해석해요. 클라우드 샌드박스는 sbx mcp add로 로컬 MCP 저장소에 등록된 서버를 사용하지 않아요.

기존 클라우드 샌드박스 게이트웨이가 보고한 서버를 나열하거나, 한 샌드박스의 게이트웨이를 검사해요:

$ sbx --cloud mcp ls
$ sbx --cloud mcp ls cloud-project

계정 목록은 게이트웨이가 보고한 서버를 그것을 쓰는 샌드박스와 함께 보여줘요. 쓰이지 않는 서버 구성과 게이트웨이가 건너뛴 서버는 생략해요. 샌드박스 뷰는 건너뛴 서버를 포함해요.

클라우드 접근 진단하기 (Diagnose cloud access)

CLI, Docker 로그인, 클라우드 API 연결, 계정 접근을 확인해요:

$ sbx --cloud diagnose

이 확인은 로컬 샌드박스 데몬을 요구하지 않아요. 로컬 진단은 Troubleshooting 문서를 보세요.

알려진 제한 사항 (Known limitations)

Docker exec와 건강 검사 (Docker exec and healthchecks)

클라우드 샌드박스 안에서 Docker를 실행할 때, docker exec가 대상 컨테이너의 파일시스템 대신 샌드박스 VM 파일시스템에 접근할 수 있어요. 같은 실행 경로를 쓰는 docker compose exec와 Docker 건강 검사(healthcheck)에도 영향을 줘요.

애플리케이션 파일, 바이너리, 마운트된 데이터를 찾지 못해 명령이 실패할 수 있어요. 잘못된 파일을 읽거나 쓰면서 성공할 수도 있어요. 성공한 종료 상태가 명령이 대상 컨테이너의 파일시스템을 사용했다는 확인은 아니에요.

건강 검사가 잘못된 결과를 보고할 수 있어요. condition: service_healthy에 의존하는 Compose 서비스는 필요한 서비스가 실행 중이어도 막혀 있을 수 있어요.

docker run이 시작한 컨테이너의 주 프로세스는 올바른 파일시스템을 사용해요. 워크플로가 지원하는 곳에서는 설정이나 준비 상태 검사를 컨테이너의 주 명령으로 실행하세요. 이렇게 하면 그 명령에 대해 영향을 받는 exec 경로를 피하지만, exec 동작이나 지속적인 건강 모니터링을 복원하지는 않아요.

더 알아보기 (Learn more)

관련 문서와 심화 내용은 원문을 참고해 주세요.