Claude Code

샌드박스에서 Claude Code를 어떻게 실행하고 설정하는지 설명해 드릴게요.

출처: 문서

본문

아래 지침은 로컬 샌드박스에 적용돼요. 클라우드 인증과 사용법은 클라우드 에이전트 인증과 클라우드 샌드박스 사용하기 문서를 보세요.

공식 문서: Claude Code

빠른 시작 (Quick start)

프로젝트 디렉터리를 가리키며 샌드박스에서 Claude Code를 실행해요:

$ sbx run claude ~/my-project

현재 디렉터리에서 특정 프롬프트와 함께 Claude를 시작하려면:

$ sbx run --name my-sandbox claude -- "Add error handling to the login function"

-- 뒤의 모든 내용은 Claude Code에 그대로 전달돼요. 프롬프트를 파일에서 파이프로 넣고 싶다면 -- "$(cat prompt.txt)" 형식으로 쓸 수도 있어요.

마운트 없는 샌드박스(mountless sandbox)를 만들려면 워크스페이스 경로 없이 sbx create를 쓰고, 이름으로 붙여서(attach) 사용하면 돼요.

인증 (Authentication)

기본 Anthropic 모델을 쓸 때는 Claude Code가 Anthropic API 키 또는 Claude 구독이 필요해요. 다른 모델은 로컬 모델 사용하기 문서를 참고하세요.

API 키: 저장된 시크릿(stored secrets)으로 키를 저장해요:

$ sbx secret set anthropic

Claude 구독: API 키가 없으면 Claude Code 안에서 /login 명령을 사용해 OAuth로 인증해요.

설정 (Configuration)

샌드박스는 호스트의 사용자 수준 설정(예: ~/.claude)을 가져오지 않아요. 샌드박스 안에서는 작업 디렉터리의 프로젝트 수준 설정만 쓸 수 있어요. 해결 방법은 "샌드박스가 내 사용자 수준 에이전트 설정을 안 쓰는 이유는?" 문서를 참고하세요.

원격 제어 (Remote control)

샌드박스 안에서 Claude Code의 /remote-control 명령을 쓰려면 claude.remoteControl을 켜세요:

$ sbx settings set claude.remoteControl true

기본 시작 명령 (Default startup command)

추가 인자 없이 샌드박스는 다음을 실행해요:

claude --dangerously-skip-permissions

-- 뒤의 인자는, 첫 인자가 플래그(-로 시작)일 때 기본 플래그 뒤에 추가돼요. 그래서 --dangerously-skip-permissions가 유지돼요:

$ sbx run --name <sandbox-name> -- -c  # claude --dangerously-skip-permissions -c 를 실행

첫 인자가 agents 서브커맨드 같은 일반 단어면 기본 값을 대신 대체해요.

사용 가능한 옵션은 Claude Code CLI reference 문서를 보세요.

에이전트 뷰 (Agents view)

Claude Code의 agents view는 작업을 병렬로 실행하는 백그라운드 세션을 시작해요. 변경 사항을 샌드박스 안에 유지하려면 clone mode와 함께 쓰면 돼요:

$ sbx run --clone claude . -- agents

이 호출은 기본 시작 명령을 대체하므로 --dangerously-skip-permissions가 포함되지 않고, 샌드박스 안에서 우회 권한(bypass-permissions) 모드로 전환할 수도 없어요. 이 문제를 피하려면 Claude Code의 auto mode를 쓰거나 플래그를 명시적으로 전달하세요:

$ sbx run --clone claude . -- --dangerously-skip-permissions agents

Claude Code는 백그라운드 세션의 변경을 분리하기 위해 브랜치나 워크트리를 쓸 수 있어요. 이는 작업, Claude Code 설정, 프로젝트 지침에 따라 달라져요. --clone 플래그는 이 동작을 제어하지 않아요. Claude Code가 만들 브랜치와 워크트리는 호스트 체크아웃이 아니라 샌드박스 안에 생겨요.

세션이 만든 브랜치를 검토하려면 호스트에서 sandbox-<sandbox-name> 원격(remote)을 fetch 하세요:

$ git fetch sandbox-<sandbox-name>
$ git diff main..sandbox-<sandbox-name>/<branch>

clone 모드의 자세한 내용은 Git 워크플로 문서를 보세요.

기본 이미지 (Base image)

샌드박스는 docker/sandbox-templates:claude-code를 사용해요. 이 베이스 위에 자신만의 이미지를 만들려면 Base images 문서를 보세요.

로컬 모델 사용하기 (Use a local model)

로컬 모델, 호스팅 제공 업체, 커스텀 추론 엔드포인트는 로컬/호스팅 모델 사용하기 문서를 참고하세요.

더 알아보기 (Learn more)

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