사용법

사용법 (Usage)

sbx의 일상적인 명령 중심 사용법을 알아볼게요.

출처: 문서

본문

이 페이지는 로컬 샌드박스를 설명해요. 클라우드 명령, 파일 전송, 포트, 만료는 클라우드 샌드박스 사용을 참고하세요.

이 페이지를 일상적인 sbx 작업을 위한 명령 중심 가이드로 사용하세요. 시나리오 기반 권장 사항은 워크플로우 패턴을 참고하세요.

로그인 (Sign in)

터미널에서 로그인하세요:

$ sbx login

브라우저를 사용할 수 없는 스크립트나 CI 러너는 CI 및 헤드리스 사용을 참고하세요.

시작, 중지, 제거 (Start, stop, and remove)

기본 워크플로우는 run으로 시작하고, ls로 상태를 확인하고, stop으로 일시 중지하고, rm으로 정리해요:

$ sbx run claude                    # start an agent in the current directory
$ sbx ls                            # see what's running
$ sbx stop my-sandbox               # pause it
$ sbx rm my-sandbox                 # delete it entirely

sbx rm은 샌드박스를 삭제하기 전에 확인을 요구해요. 프롬프트를 건너뛰려면 --force를 사용하세요. 이 플래그는 샌드박스에 활성 세션(열린 attach, SSH 연결, 진행 중인 SFTP 전송)이 있을 때도 제거를 허용해요:

$ sbx rm --force my-sandbox

깨끗한 상태가 필요하면 샌드박스를 제거하고 다시 실행하세요:

$ sbx stop my-sandbox
$ sbx rm my-sandbox
$ sbx run claude

중지된 모든 로컬 샌드박스를 제거하려면 sbx prune을 사용하세요. 실행 중인 샌드박스는 절대 제거되지 않아요. 제거될 샌드박스를 미리 보거나, 지난 주 내에 중지된 샌드박스를 걸러내려면:

$ sbx prune --dry-run
$ sbx prune --filter until=168h

until 필터는 샌드박스가 중지된 시각을 사용해요. 168h 같은 기간, RFC 3339 타임스탬프, Unix 타임스탬프를 받아요. 옛 since=<duration> 필터는 계속 지원돼요.

플래그 없이 sbx prune을 실행하면 모든 중지된 샌드박스를 확인하고 제거해요.

워크스페이스 선택 (Choose a workspace)

sbx run은 워크스페이스 경로를 전달하지 않으면 현재 디렉터리를 마운트해요. 다른 디렉터리를 마운트하려면 경로를 전달하세요:

$ sbx run claude
$ sbx run claude ~/my-project

첫 워크스페이스 경로가 기본 워크스페이스(primary workspace)예요. 에이전트가 거기서 시작하고, sbx exec가 기본 작업 디렉터리로 사용해요. 호스트 디렉터리는 샌드박스 안의 같은 절대 경로에 마운트돼요. sbx run에 경로를 전달하지 않으면 현재 디렉터리가 기본 워크스페이스예요.

sbx 버전 0.42.0부터 sbx create의 워크스페이스 경로는 선택 사항이에요. 생략하면 호스트 워크스페이스 바인드 마운트 없는 마운트 없는 샌드박스를 만들고, 이름으로 샌드박스에 붙으세요:

$ sbx create --name scratch claude
$ sbx run --name scratch

마운트 없는 샌드박스에서 에이전트는 템플릿 이미지의 작업 디렉터리에서 시작해요. Docker 제공 템플릿은 /home/agent/workspace를 사용해요. 그곳의 파일은 중지·재시작에도 유지되지만 샌드박스를 제거하면 삭제돼요. 다시 연결할 수 있도록 샌드박스에 이름을 주고, 샌드박스와 호스트 간 파일 전송에는 sbx cp를 사용하세요.

재연결 및 이름 지정 (Reconnect and name sandboxes)

샌드박스는 에이전트가 종료된 후에도 유지돼요. 같은 워크스페이스 경로를 다시 실행하면 새 샌드박스를 만들지 않고 기존 샌드박스에 재연결돼요:

$ sbx run claude ~/my-project  # creates sandbox
$ sbx run claude ~/my-project  # reconnects to same sandbox

--name으로 샌드박스에 명시적 정체성을 주세요:

$ sbx run --name my-project claude

이름 있는 샌드박스가 있으면 어떤 작업 디렉터리에서든 sbx run --name으로 다시 붙을 수 있어요. 재붙을 때 에이전트 이름은 생략할 수 있어요:

$ sbx run --name my-project        # re-attaches from anywhere
$ sbx run claude --name my-project # same, with agent confirmed

같은 워크스페이스에 여러 샌드박스를 실행하려면 각각에 고유한 이름을 주세요:

$ sbx run claude --name feature ~/my-project
$ sbx run claude --name spike ~/my-project

붙지 않고 생성 (Create without attaching)

sbx run은 샌드박스를 만들고 에이전트에 붙어요. 붙지 않고 현재 디렉터리가 마운트된 샌드박스를 백그라운드로 만들려면:

$ sbx create --name my-project claude .

경로를 생략하면 마운트 없는 샌드박스를 만들 수 있어요. 나중에 sbx run --name으로 붙으세요:

$ sbx create --name scratch claude
$ sbx run --name scratch

sbx create가 끝나면 로컬 샌드박스는 세션 없이 실행 중인 것이 없을 때 자동으로 중지돼요. 파일과 구성은 유지돼요. sbx run --name <sandbox-name>으로 다시 시작하고 에이전트에 붙어요.

환경 변수 설정 (Set environment variables)

[!NOTE] -e/--env와 --env-file 플래그는 sbx 버전 0.39.0 이상이 필요해요.

sbx run이나 sbx create에 -e 또는 --env를 전달해 샌드박스에 환경 변수를 설정하세요:

$ sbx run -e LOG_LEVEL=debug claude

값 없는 변수 이름을 지정하면 호스트 환경에서 값을 복사해요:

$ export API_URL=https://api.example.com
$ sbx run -e API_URL claude

여러 변수를 로드하려면 환경 파일을 하나 이상 전달하세요:

$ sbx create --name my-project --env-file .env.sandbox claude .

플래그는 docker run 우선순위 규칙을 따르니다. -e로 전달된 값은 환경 파일의 값을 덮어써요. 환경 파일을 여러 개 전달하면 나중 파일의 값이 이전 파일의 같은 변수를 덮어써요.

두 명령이 샌드박스를 만들 때 변수는 샌드박스에 저장돼요. sbx run이 시작한 에이전트 세션에도 사용할 수 있어요. sbx run이 기존 샌드박스에 재붙을 때 변수는 샌드박스의 저장된 환경을 바꾸지 않고 그 에이전트 세션에 적용돼요. 단일 명령에만 변수를 설정하려면 sbx exec -e 또는 sbx exec --env-file을 사용하세요.

기존 샌드박스의 향후 세션에 변수를 유지하려면 /etc/sandbox-persistent.sh에 export를 추가하세요:

$ sbx exec <sandbox-name> bash -c "echo 'export INTERNAL_API_URL=https://api.example.com' >> /etc/sandbox-persistent.sh"

bash -c 래퍼는 >> 리다이렉트가 호스트가 아니라 샌드박스 안에서 실행되게 해요. 파일은 Bash가 샌드박스 안에서 시작할 때(대화형 세션과 sbx run으로 시작한 에이전트 포함) source돼요. sbx exec에 직접 전달한 명령은 셸을 시작하지 않아요. 영구 환경 파일의 변수가 필요하면 그 명령을 bash -c로 감싸세요.

파일에 추가한 변수는 이후에 시작된 세션과 에이전트에만 적용돼요. 새 값을 적용하려면 실행 중인 에이전트를 재시작하거나 샌드박스를 중지·시작하세요.

환경 변수는 샌드박스 안의 프로세스가 읽을 수 있어요. API 키와 다른 자격 증명은 지원 서비스의 경우 sbx secret set, 알려진 호스트로 보내는 자격 증명은 실험적 sbx secret set-custom을 사용하세요. 그러면 호스트 측 프록시가 실제 값을 에이전트에 노출하지 않고 주입할 수 있어요.

샌드박스 안에서 명령 실행 (Run commands inside a sandbox)

실행 중인 샌드박스 안에서 셸을 얻으려면 sbx exec를 사용하세요:

$ sbx exec -it <sandbox-name> bash

--workdir가 없으면 명령은 샌드박스의 기본 워크스페이스에서 시작해요. 마운트 없는 샌드박스에서는 컨테이너 이미지의 작업 디렉터리에서 시작해요.

sbx exec는 포그라운드에서 명령을 실행해요. 분리 실행(-d 또는 --detach)은 지원되지 않아요.

대화형 모드 (Interactive mode)

하위 명령 없이 sbx를 실행하면 대화형 터미널 대시보드가 열려요:

$ sbx

대시보드는 모든 샌드박스를 실시간 상태, CPU, 메모리 사용량과 함께 카드로 보여줘요. 여기서 다음을 할 수 있어요:

  • Create 샌드박스(c).
  • Start/stop 샌드박스(s).
  • Attach 에이전트 세션(Enter), sbx run과 같음.
  • Open a shell 샌드박스 안에서(x), sbx exec과 같음.
  • Remove 샌드박스(r).

대시보드에는 샌드박스가 만든 아웃바운드 연결을 모니터링하고 네트워크 규칙을 관리할 수 있는 네트워크 거버넌스 패널도 있어요. tab으로 샌드박스 패널과 네트워크 패널을 전환하세요.

네트워크 패널에서 연결 로그를 탐색하고, 특정 호스트를 허용하거나 차단하고, 사용자 정의 네트워크 규칙을 추가할 수 있어요. 모든 키보드 단축키는 ?를 누르세요.

Git 워크스페이스 모드

기본 워크스페이스가 Git 저장소일 때, 샌드박스를 만들 때 받는 방식을 선택하세요:

  • 직접 모드는 sbx run의 기본값이에요. sbx create에 워크스페이스 경로를 전달할 때도 적용돼요. 에이전트가 작업 트리에 읽기-쓰기로 접근하고, 변경이 즉시 여러분의 호스트에 나타나요.
  • 클론 모드는 --clone을 사용해요. 에이전트가 샌드박스 안의 별도 Git 클론을 편집해요. 가져오거나 에이전트가 푸시할 때까지 그 변경은 그곳에 남아요. 호스트 저장소는 /run/sandbox/source에서도 사용할 수 있지만 읽기 전용이에요.

브랜치 전략, 샌드박스에서 작업 가져오기, 병렬 에이전트 워크플로우는 Git 워크플로우를 참고하세요. 각 모드의 보안 모델은 워크스페이스 격리를 참고하세요.

클론 모드 (Clone mode)

클론 모드 샌드박스를 만들려면 실행하거나 만들 때 --clone을 전달하세요:

$ sbx run --clone claude .

백그라운드로 샌드박스를 만들고 나중에 붙을 수도 있어요:

$ sbx create --clone --name my-sandbox claude .
$ sbx run --name my-sandbox

클론 모드에는 생성 시 몇 가지 제약이 있어요:

  • 클론 모드는 생성 시 고정돼요. 기존 샌드박스를 클론 모드로 바꾸려면 제거하고 sbx create --clone으로 다시 만드세요.
  • 클론은 생성 시 호스트 저장소가 체크아웃한 ref를 따라가요. 브랜치가 자동 생성되지는 않아요.
  • 기본 워크스페이스는 Git 저장소여야 해요. Git이 아닌 워크스페이스에는 --clone을 생략하세요.
  • 클론 모드는 메인 워크트리 외부의 Git 워크트리 안에서 거부돼요. 읽기 전용 바인드 마운트가 워크트리의 .git 포인터 파일을 해석할 수 없기 때문이에요. 메인 저장소 체크아웃에서 sbx create --clone <agent> .를 실행하세요.
  • 클론 모드 샌드박스를 제거하면 샌드박스 안의 클론이 사라져요. 제거 전에 보관하고 싶은 커밋을 가져오거나 푸시하세요.

여러 워크스페이스 (Multiple workspaces)

기본 워크스페이스와 함께 추가 디렉터리를 샌드박스에 마운트할 수 있어요. 첫 경로가 기본 워크스페이스예요 — 에이전트가 여기서 시작하고, --clone을 사용하면 샌드박스의 컨테이너 내 Git 클론이 이 디렉터리에서 채워져요. 추가 워크스페이스는 항상 직접 마운트돼요.

각 워크스페이스 경로는 호스트에서와 같은 절대 경로로 샌드박스 안에 나타나요. :ro를 붙여 추가 워크스페이스를 읽기 전용으로 마운트하세요 — 에이전트가 수정하면 안 되는 참조 자료나 공유 라이브러리에 유용해요:

$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro

별도 프로젝트를 나란히 실행할 수도 있어요. 끝나면 사용하지 않는 샌드박스를 제거해 디스크 공간을 회수하세요:

$ sbx run claude ~/project-a
$ sbx run claude ~/project-b
$ sbx rm <sandbox-name>       # when finished

호스트와 샌드박스 간 파일 복사 (Copy files between host and sandbox)

sbx cp로 호스트와 샌드박스 사이에서 파일이나 디렉터리를 복사하세요. 마운트된 워크스페이스에 속하지 않는 생성된 출력, 로그, 설정 파일 같은 일회성 파일에 유용해요. 샌드박스 경로는 절대 경로여야 해요. sbx cp는 . 같은 상대 경로를 샌드박스의 기본 작업 디렉터리 기준으로 해석하지 않아요.

예를 들어 Docker가 제공하는 에이전트 템플릿이 사용하는 기본 작업 디렉터리로/에서 파일을 복사하세요:

$ sbx cp ./config.json my-sandbox:/home/agent/workspace/
$ sbx cp my-sandbox:/home/agent/workspace/output.log ./
$ sbx cp ./src/ my-sandbox:/home/agent/workspace/src

복사의 한쪽은 SANDBOX:PATH를 사용해야 해요. 두 샌드박스 사이에 직접 복사하는 것은 지원되지 않아요.

포트 게시 (Publish ports)

샌드박스는 네트워크로 격리되어 있어요 — 여러분의 브라우저나 로컬 도구는 기본적으로 안에서 실행되는 서버에 도달할 수 없어요. 8080:3000 포트 매핑은 샌드박스 포트 3000을 호스트 포트 8080에 게시해요.

필요한 포트를 알고 있다면 샌드박스를 만들 때 게시하세요:

$ sbx run --publish 8080:3000 --name my-sandbox claude

기존 샌드박스는 sbx ports로 호스트에서 트래픽을 전달하세요. 중지된 로컬 샌드박스에 포트를 게시하면 먼저 시작돼요:

$ sbx ports my-sandbox --publish 8080:3000
$ open http://localhost:8080

직접 고르는 대신 OS가 빈 호스트 포트를 고르게 하려면 샌드박스 포트만 지정하세요. 그런 다음 sbx ports로 어떤 호스트 포트가 할당됐는지 확인하세요:

$ sbx ports my-sandbox --publish 3000
$ sbx ports my-sandbox

sbx ls는 각 샌드박스 옆에 활성 포트 매핑을 보여줘요. sbx ports는 그것들을 상세히 나열해요.

$ sbx ls
SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
my-sandbox      claude  running  127.0.0.1:8080->3000/tcp4 /home/user/proj

포트 전달을 중지하려면:

$ sbx ports my-sandbox --unpublish 8080:3000

sbx run이 기존 샌드박스에 재붙을 때 --publish를 무시해요. 그 샌드박스에 포트를 게시하려면 sbx ports를 사용하세요. 개발 서버와 호스트 서비스 레시피는 로컬 서비스를 참고하세요.

유지되는 것 (What persists)

샌드박스가 존재하는 동안 설치된 패키지, Docker 이미지, 구성 변경, 명령 기록, 마운트 없는 워크스페이스 파일이 모두 중지·재시작에도 유지돼요. 샌드박스를 제거하면 안의 모든 것이 삭제돼요. 클론 소스로 사용된 저장소를 포함한 호스트 워크스페이스 파일과 공유 에이전트 스킬 저장소는 호스트에 남아요. 컨테이너 파일시스템의 변경을 담으려면 템플릿으로 저장하세요. 소스로 정의된 재현 가능한 환경에는 kit 작성을 참고하세요.

샌드박스를 템플릿으로 저장 (Saving a sandbox as a template)

도구나 구성을 대화형으로 설정한 후 샌드박스의 컨테이너 파일시스템을 재사용 가능한 템플릿 이미지로 저장하세요. 템플릿은 이미지 내용을 포함해요. 에이전트 kit가 자격 증명·네트워크 규칙 같은 런타임 설정을 여전히 제공해요. 여기 예시는 내장 에이전트로 템플릿을 재사용해요.

저장된 템플릿은 전체 샌드박스의 백업이 아니에요. 호스트 워크스페이스와 /var/lib/docker의 Docker 저장소를 포함한 마운트된 파일시스템은 포함되지 않아요. 그 마운트의 데이터는 별도로 저장하세요.

[!WARNING] 샌드박스 저장은 그 컨테이너 파일시스템의 파일(거기에 저장된 비밀 포함)을 담아요. API 키, 토큰, 기타 자격 증명을 샌드박스에 수동으로 추가했다면 저장된 템플릿에 포함되고 배포하는 모든 사람과 공유돼요. 비밀을 템플릿에 넣지 않으려면 대신 sbx secret set으로 관리하세요 — 프록시가 런타임에 주입하므로 파일시스템에 절대 기록되지 않아요. 자세한 내용은 자격 증명 관리를 참고하세요.

저장 및 재사용 (Save and reuse)

샌드박스를 중지하고(또는 CLI의 안내를 따르고) 이름과 태그로 저장하세요:

$ sbx template save my-sandbox my-template:v1

이미지는 샌드박스 런타임의 로컬 이미지 저장소에 저장돼요. -t 플래그로 새 샌드박스를 만들세요:

$ sbx run -t my-template:v1 claude

템플릿 나열 및 제거 (List and remove templates)

저장된 모든 템플릿 나열:

$ sbx template ls

더 이상 필요 없는 템플릿 제거:

$ sbx template rm my-template:v1

내보내기 및 가져오기 (Export and import)

저장된 템플릿을 공유하거나 다른 머신으로 옮기려면 tar 파일로 내보내세요:

$ sbx template save my-sandbox my-template:v1 --output my-template.tar

다른 머신에서 tar 파일을 로드하고 사용하세요:

$ sbx template load my-template.tar
$ sbx run -t my-template:v1 claude

제한 사항 (Limitations)

에이전트 구성 파일은 샌드박스가 생성될 때 항상 다시 만들어져요. /home/agent/.claude/settings.json, /home/agent/.claude.json 같은 사용자 수준 에이전트 구성 파일의 변경은 저장된 템플릿에 유지되지 않아요.

저장된 템플릿이 sbx run에서 지정한 것과 다른 에이전트용으로 만들어졌다면 경고가 나와요. 예를 들어 Claude 샌드박스를 저장하고 codex로 실행하면:

⚠ WARNING: template "my-template:v1" was built for the "claude" agent but you are using "codex".
  The sandbox may not work correctly. Consider using: sbx run -t my-template:v1 claude

템플릿 로드 (Load a template)

레지스트리의 템플릿 이미지에서 샌드박스를 만들려면 전체 이미지 참조를 --template에 전달하세요. 이미지가 준비된 에이전트를 사용하세요:

$ sbx run --template docker.io/my-org/my-template:v1 claude

sbx는 Docker 명령과 달리 이미지 참조에 Docker Hub 도메인(docker.io)을 자동으로 추가하지 않아요. 사용 가능한 이미지와 내장 에이전트 워크플로우는 기본 이미지를 참고하세요.

[!NOTE] Docker Sandboxes가 사용하는 Docker 데몬은 레지스트리에서 템플릿을 직접 풀해요. 호스트의 로컬 Docker 데몬의 이미지 저장소를 공유하지 않아요. Docker Hub 이미지 풀을 조직의 레지스트리 인프라로 라우팅하려면 레지스트리 미러를 구성하세요.

[!IMPORTANT] Docker Hub의 경우 sbx는 sbx login 세션을 재사용해 사설 이미지를 풀해요. 다른 레지스트리(GitHub Container Registry, ECR, ACR, 자체 호스팅 Nexus 등)는 샌드박스를 실행하기 전에 sbx secret set --registry로 풀 자격 증명을 저장하세요:

$ gh auth token | sbx secret set --registry ghcr.io --password-stdin

자격 증명이 저장되지 않으면 Docker Hub가 아닌 레지스트리에서의 풀은 익명이고 사설 이미지는 풀에 실패해요.

로컬에서 빌드한 이미지는 레지스트리에서 풀하는 대신 tar로 저장하고 샌드박스 런타임에 직접 로드하세요:

$ docker image save my-org/my-template:v1 -o my-template.tar
$ sbx template load my-template.tar
$ sbx run --template my-org/my-template:v1 claude

sbx template load는 tar를 샌드박스 런타임의 이미지 저장소로 가져오므로, 이미지가 샌드박스 생성 시 레지스트리에서 도달 가능할 필요가 없어요.

템플릿 캐싱 (Template caching)

샌드박스를 만들 때 sbx는 기본적으로 레지스트리에서 템플릿 이미지를 확인하고 누락되거나 업데이트된 레이어를 다운로드해요. 풀이 실패하고 이미지가 로컬에 캐시되어 있으면 캐시된 이미지를 사용할 수 있어요. 캐시된 이미지는 샌드박스 생성과 삭제를 넘어 유지되고, sbx reset을 실행하면 지워져요.

에이전트 업데이트 (Updating agents)

에이전트 템플릿에는 에이전트 버전이 포함되며, 이는 에이전트의 최신 릴리스와 다를 수 있어요. sbx CLI를 업데이트하거나 업데이트된 템플릿을 풀해도 기존 샌드박스 안의 에이전트는 업데이트되지 않아요.

설치된 에이전트를 업데이트하려면 샌드박스 안(샌드박스 셸 또는 sbx exec)에서 문서화된 업데이트 명령을 실행하세요. 업데이트된 버전을 사용하려면 에이전트 세션을 재시작하세요. 업데이트는 샌드박스 중지·시작에도 유지되지만 샌드박스를 제거하면 삭제돼요. 업데이트된 에이전트를 다른 샌드박스에서 재사용하려면 템플릿으로 저장하세요.

더 알아보기 (Learn more)