Claude Code 샌드박스 모범 사례는 한 가지 규칙에서 시작합니다: Claude Code가 사람의 승인 없이 파일을 편집하고 명령을 실행할 수 있다면, 랩톱이나 공유 CI 러너가 아니라 격리된 워크스페이스에서 실행해야 합니다. 이는 헤드리스 모드에서 훨씬 더 중요합니다. 헤드리스 실행의 핵심은 에이전트가 사람이 "허용"을 클릭하기를 기다리지 않고 파일 편집, 셸 명령, 종속성 설치를 계속 진행할 수 있다는 것이기 때문입니다. Novita의 Claude Code 샌드박스 가이드는 정확한 템플릿 명령과 플래그에 대한 신뢰할 수 있는 출처입니다. 이 글은 팀이 일반적으로 다음으로 필요로 하는 부분에 초점을 맞춥니다: 왜 Claude Code를 샌드박스에 넣어야 하는지, 그렇게 하지 않으면 무엇이 잘못될 수 있는지, 그리고 템플릿을 실제 워크플로에 연결하기 전에 추가해야 할 프로덕션 제어가 무엇인지.
Claude Code가 헤드리스 모드에서 샌드박스를 필요로 하는 이유
Claude Code는 코드 초안 작성 이상의 일을 하기 때문에 유용합니다. 파일을 읽고, 파일을 편집하고, 셸 명령을 실행하고, 테스트 출력을 확인한 후 반복합니다. 바로 이러한 능력 때문에 대화형 개발자 세션에서 무인 자동화로 전환할 때 샌드박스가 필요한 것입니다.
로컬 터미널에서는 사람이 보통 잘못된 아이디어를 일찍 발견합니다. 열어둔 저장소를 볼 수 있고, 명령이 잘못된 디렉터리를 건드릴 때 알아차릴 수 있으며, 의심스러워 보이는 설치를 중단할 수 있습니다. 헤드리스 워크플로에서는 이러한 자연스러운 체크포인트가 사라집니다. 에이전트는 사용자가 제공한 지시와 환경만 볼 수 있습니다.
그래서 올바른 비교는 "Claude Code vs. Claude Code 없음"이 아닙니다. "실제 머신에서 실행되는 Claude Code"와 "격리된 실행 경계 내부의 Claude Code"의 비교입니다. 에이전트가 자율적으로 작동할 수 있다면 워크스페이스는 안전 모델의 일부가 됩니다.
위험 표면은 상당히 구체적입니다:
| 위험 영역 | 샌드박스가 없을 때 무엇이 잘못될 수 있는가 | 샌드박스가 바꾸는 것 |
|---|---|---|
| 저장소 범위 | 에이전트가 잘못된 저장소, 브랜치 또는 추적되지 않은 로컬 파일을 편집합니다 | 각 작업에 범위가 지정된 체크아웃, 알려진 기준 커밋, 일회용 브랜치가 제공됩니다 |
| 셸 실행 | 명령이 호스트 머신이나 공유 러너에서 실행됩니다 | 명령은 격리된 파일시스템과 프로세스 경계 내에 유지됩니다 |
| 종속성 설치 | npm, pip 또는 기타 패키지 설치가 호스트에서 임의의 스크립트를 실행합니다 |
패키지 설치는 정책과 로그가 있는 일회용 환경에서 이루어집니다 |
| 비밀 | 에이전트가 볼 수 있는 환경 변수에 광범위한 개발자 또는 프로덕션 자격 증명이 포함될 수 있습니다 | 작업 범위의 비밀을 샌드박스 세션으로 제한할 수 있습니다 |
| 검토 | 유일한 기록은 채팅 요약 또는 터미널 트랜스크립트입니다 | Diff, 로그, stdout, stderr 및 아티팩트를 검토용으로 캡처할 수 있습니다 |
Claude에 한정되지 않는 더 광범위한 샌드박스 설계 체크리스트가 필요하다면 Coding Agent Sandbox: How to Run Agent-Generated Code Safely와 Run Claude Code or Managed Agents in an Isolated Sandbox를 읽어보세요. 여기서 차이점은 Claude Code에는 이미 구체적인 CLI 워크플로가 있다는 점이므로, 인프라 문제는 더 구체적이 됩니다: 루프에 사람이 없을 때 해당 CLI를 어떻게 안전하게 실행할 것인가?
--dangerously-skip-permissions를 사용하면 무엇이 달라지나요
이 플래그는 많은 팀이 샌드박스 질문을 시작하는 이유입니다. 일반적인 대화형 사용에서 Claude Code는 파일을 편집하거나 도구를 실행하기 전에 물어볼 수 있습니다. 무인 자동화에서는 승인 프롬프트가 흐름을 끊기 때문에 Novita 문서는 claude-code 템플릿 안에서 claude --dangerously-skip-permissions -p "<prompt>" 헤드리스 패턴을 보여줍니다.
이는 플래그가 정의상 안전하지 않다는 뜻이 아닙니다. 안전 계층이 이동했다는 뜻입니다.
--dangerously-skip-permissions를 사용할 때 다음을 가정해야 합니다:
- Claude Code가 즉시 파일을 편집할 수 있습니다.
- Claude Code가 즉시 명령을 실행할 수 있습니다.
- Claude Code가 검토를 위해 멈추지 않고 다단계 작업을 계속할 수 있습니다.
올바른 대응은 실제 워크스테이션에서 플래그를 사용하고 좋은 결과를 기대하는 것이 아닙니다. 올바른 대응은 워크스페이스, 저장소, 명령, 비밀, 네트워크 표면이 이미 제한된 샌드박스 내부에서만 플래그를 사용하는 것입니다. 샌드박스 경계가 피해 범위(blast radius)를 줄이는 장소가 됩니다.
또한 이 설정을 문서화할 때 표현을 정확하게 유지해야 하는 이유이기도 합니다. --dangerously-skip-permissions는 로컬 머신 편의를 위한 권장 사항이 아닙니다. 헤드리스 자동화를 위한 샌드박스 전용 운영 패턴입니다. 워크플로가 여전히 개발자 랩톱, 공유 배스천 또는 프로덕션 유사 러너에서 Claude Code를 실행한다면, 승인 프롬프트를 제거했으면서 이를 대체해야 할 인프라 제어를 추가하지 않은 것입니다.
팀이 해당 환경에서 패키지 설치를 신뢰할지 아직 결정하지 못했다면 이 글을 How to Safely Allow Package Installs in AI Agent Sandboxes 및 AI Agent Sandbox Isolation Boundary Checklist와 함께 읽어보세요.
Novita의 claude-code 템플릿이 프로덕션 워크플로에 매핑되는 방식
Novita 문서의 유용한 점은 추상적인 수준에 머물지 않는다는 것입니다. 프로덕션 워크플로가 필요로 하는 실제 메커니즘을 보여줍니다.
1. 헤드리스 -p 및 --print 모드
문서에서는 비대화형 -p 모드로 Claude Code를 사용하여 실행이 프롬프트를 받고 결과를 출력한 후 종료할 수 있도록 합니다. 이는 헤드리스 자동화가 깔끔한 프로그래밍 방식 계약을 필요로 하기 때문에 중요합니다. 사람 세션에 연결된 장기 대화형 터미널을 원하지 않습니다. 시작하고 관찰하고 종료할 수 있는 작업 지향 실행을 원합니다.
이는 Claude Code CLI Documentation에서 논의된 것과 같은 구분입니다: 대화형 Claude Code는 사람 드라이버를 위한 것이고, -p와 구조화된 출력이 CLI를 스크립트와 에이전트 파이프라인에서 유용하게 만듭니다.
2. ~/.claude/settings.json을 통한 사용자 지정 모델 라우팅
Novita 문서는 많은 팀이 놓치는 실용적인 세부 사항도 보여줍니다: 샌드박스 안에 ~/.claude/settings.json을 작성하여 Claude Code가 env 블록을 통해 API 토큰, 기본 URL, 모델 구성을 받도록 하는 것입니다. 이 패턴이 중요한 이유는 두 가지입니다.
첫째, 런타임을 자체 포함형으로 유지합니다. 샌드박스는 개발자 머신에 있는 것을 상속하는 대신 작업에 필요한 정확한 Claude 관련 구성으로 부팅할 수 있습니다.
둘째, 명시적인 환경 제어를 지원합니다. 워크플로가 사용자 지정 백엔드와 함께 Claude Code를 사용한다면 샌드박스 구성은 숨겨진 개인 셸 상태가 아니라 검토된 설정의 일부가 됩니다.
3. 범위가 지정된 자격 증명을 사용한 실제 저장소 클로닝
문서에서는 대상 경로, 얕은 클론 깊이, 프라이빗 저장소용 GitHub 토큰을 사용하는 sandbox.git.clone(...)을 보여줍니다. 이것은 사소한 편의 기능이 아닙니다. 재현 가능한 작업 워크스페이스와 모호한 디렉터리에서 작업하는 에이전트 사이의 차이입니다.
프로덕션에서 더 안전한 패턴은 다음과 같습니다:
- 작업에 필요한 저장소만 클론합니다.
- 워크플로가 재현성을 요구할 때 시작 ref 또는 커밋을 고정합니다.
- 에이전트 변경 사항에는 작업 브랜치를 사용합니다.
- 작업에 필요한 것만 읽거나 쓸 수 있는 범위가 지정된 Git 자격 증명을 전달합니다.
저장소에 아직 쓰기 액세스가 필요하지 않다면 에이전트가 결국 PR을 열 수 있다는 이유만으로 쓰기 액세스를 부여하지 마세요.
4. 다단계 작업을 위한 구조화된 출력과 session_id
문서는 두 번째 유용한 패턴을 보여줍니다: --output-format json으로 Claude Code를 시작하고, 반환된 session_id를 파싱한 다음, --resume <session_id>로 계속 진행하는 것입니다. 이것이 일회성 코드 편집을 프로그래밍 방식으로 관리할 수 있는 다단계 워크플로로 바꿔줍니다.
이는 다음과 같은 작업에 적합합니다:
- 1단계: 저장소를 검사하고 리팩터링 계획을 생성
- 2단계: 동일한 세션을 재개하고 한 조각을 구현
- 3단계: 다시 재개하여 후속 검증 또는 정리 실행
중요한 모범 사례는 "항상 resume을 사용하라"는 것이 아닙니다. "의도적으로 resume하라"는 것입니다. 워크플로가 연속성의 이점을 얻는다면 같은 샌드박스에서 같은 세션을 재개하세요. 작업을 독립적으로 검토할 수 있어야 한다면 상태를 암시적으로 이월하는 대신 새 샌드박스를 시작하세요.
5. 작업 후 워크스페이스 종료
Novita 문서는 샌드박스를 종료하는 것으로 예제를 마칩니다. 이것이 바로 프로덕션에서 원하는 습관입니다. 헤드리스 코딩 에이전트는 오래된 워크스페이스, 백그라운드 프로세스, 남아 있는 자격 증명을 조용히 축적해서는 안 됩니다. 일회용 환경은 기록이 있는 수수께끼 같은 머신보다 이해하기 쉽습니다.
해당 런타임 모델에 대한 더 큰 아키텍처 그림을 원한다면 Building a Coding Agent with Novita’s Agent Sandbox가 함께 읽기 좋은 자료입니다.
Claude Code 샌드박스 모범 사례 체크리스트
다음 체크리스트는 문서 워크플로의 프로덕션 버전입니다. Novita 템플릿의 정확한 메커니즘을 유지하면서 자동화 파이프라인이 일반적으로 필요로 하는 제어를 추가합니다.
- 작업당 샌드박스 하나: 여러 개의 관련 없는 작업을 하나의 장기 실행 Claude Code 환경에 지정하지 마세요. 새 워크스페이스는 시작 저장소 상태를 명확하게 하고 종료를 더 쉽게 만듭니다.
- 범위가 지정된 Git 액세스: Claude Code가 저장소를 클론하고 검사하기만 하면 되는 경우 읽기 전용 토큰을 사용하세요. 브랜치를 푸시해야 한다면 해당 저장소와 해당 워크플로에 범위가 지정된 토큰을 사용하세요. 상속된 개인 자격 증명을 피하세요.
- 샌드박스 패키지 설치: Claude Code는 빌드나 테스트 실패를 재현하기 위해 종종 종속성이 필요합니다. 괜찮지만, 설치는 운영자 머신이 아니라 로그와 정책이 있는 샌드박스 내부에서 이루어져야 합니다. 다른 코드 변경과 마찬가지로 lockfile 변경 사항을 검토하세요.
- 셸 출력을 증거로 취급하세요: stdout, stderr, 종료 코드, 실제로 실행된 명령을 캡처하세요. 에이전트의 최종 요약은 유용하지만 그 자체로 검토에 충분하지 않습니다.
- 기본 프로덕션 비밀 사용 금지: 수명이 짧거나 스테이징 전용 자격 증명을 선호하세요. 저장소를 읽고 명령을 실행할 수 있는 코딩 에이전트는 기본적으로 광범위한 클라우드 관리자 토큰이나 프로덕션 데이터베이스 자격 증명이 필요하지 않습니다.
- 결과뿐 아니라 diff를 검토하세요: 헤드리스 성공은 Claude Code가 사용자가 준 루프를 완료했다는 의미일 뿐입니다. 변경 사항이 올바르거나 출시할 준비가 되었다는 의미는 아닙니다. 변경된 파일, 종속성 변경, 명령 출력, 생성된 아티팩트를 검토하세요.
--dangerously-skip-permissions를 샌드박스 로컬로 유지하세요: 이는 이 설정에서 가장 중요한 운영 규칙입니다. 이 플래그는 격리된 일회용 워크스페이스 안에 있어야 합니다. 실제 머신에서 무인 Claude Code를 실행하는 지름길로 사용해서는 안 됩니다.- 실행과 릴리스를 분리하세요: Claude Code가 패치를 검사, 편집, 테스트, 준비하는 것은 허용될 수 있습니다. 그것이 병합, 게시 또는 배포 결정까지 소유해야 한다는 뜻은 아닙니다. 이러한 작업은 사람 또는 명시적인 정책 게이트 뒤에 두세요.
- 의도적으로 resume하세요: 작업이 실제로 연속성의 이점을 얻을 때
--resume <session_id>를 사용하세요. 재현성에 대한 깨끗한 테스트가 필요하거나 한 작업이 다른 작업의 상태를 상속하면 안 되는 경우 샌드박스를 재설정하세요. - 전체 제공자 표면을 비교하세요: 이 워크플로를 호스팅할 위치를 선택한다면 환경이 Claude Code를 실행할 수 있는지 여부만 보지 마세요. 세션 수명 주기, 저장소 인체공학, 로그, 일시 중지 및 재개 동작, 운영상의 트레이드오프를 비교하세요. 이 관점에서는 E2B vs. Daytona: AI Agent Sandbox Comparison 및 Novita Sandbox: A Cost-Effective Alternative to E2B Pro with Seamless Compatibility이 관련 비교 자료입니다.
피해야 할 일반적인 실수
가장 흔한 Claude Code 샌드박스 실수는 개념적인 것이 아니라 운영적인 것입니다.
실수 1: 문서 예제를 완전한 프로덕션 정책으로 취급하기
문서는 claude-code 템플릿을 올바르게 실행하는 방법을 보여줍니다. 완전한 검토, 네트워크 또는 비밀 관리 정책이 되려고 하지는 않습니다. 구문과 런타임 메커니즘에 사용하고, 그 후에 자체 저장소 및 승인 경계를 추가하세요.
실수 2: 개발자 워크스테이션을 "샌드박스"로 재사용하기
랩톱의 터미널에서 Claude Code를 실행하는 것은 유효한 개발자 워크플로입니다. 무인 자동화를 위한 일회용 격리 런타임과는 다릅니다.
실수 3: 세션 상태를 암시적으로 남겨두기
--resume을 사용한다면 무엇을 왜 이월하고 있는지 알아야 합니다. "확실하지 않지만 편리했기 때문"이라면 더 어려운 검토 문제를 만들고 있는 것입니다.
실수 4: 실제 비밀과 탐색적 코드 작업을 혼합하기
샌드박스는 피해 범위를 줄이기 위해 존재합니다. 워크스페이스가 광범위한 자격 증명으로 프로덕션 시스템에 계속 접근할 수 있다면 가장 중요한 경계를 약화시킨 것입니다.
실수 5: 성공적인 실행을 증거보다 더 신뢰하기
에이전트는 작업을 완료해도 잘못된 변경을 하거나, 잘못된 파일을 건드리거나, 원하지 않는 종속성을 추가할 수 있습니다. 내러티브 요약뿐 아니라 diff와 로그를 검토하세요.
FAQ
--dangerously-skip-permissions는 Claude Code에 안전 장치가 전혀 없다는 뜻인가요?
이는 Claude Code가 더 이상 세션 내에서 대화형 승인을 기다리지 않는다는 뜻입니다. 헤드리스 워크플로에서 의도된 안전 계층은 세션 주변의 샌드박스 경계입니다: 격리된 저장소, 제한된 자격 증명, 샌드박스 내부의 명령 실행, 캡처된 로그, 병합 전 사람의 검토.
모든 Claude Code 자동화는 새 샌드박스에서 실행해야 하나요?
새 샌드박스는 독립적인 작업에 가장 깔끔한 기본값입니다. Resume 기반 워크플로는 동일한 다단계 작업에 연속성이 필요할 때 유용하지만, 상태는 우연이 아니라 의도적이고 검토 가능해야 합니다.
Claude Code가 샌드박스에서 패키지를 안전하게 설치할 수 있나요?
더 안전하게 만들 수는 있지만 자동으로 안전하지는 않습니다. 패키지 정책, lockfile 검토, 범위가 지정된 네트워크 액세스, 감사 로그를 사용하세요. 패키지 설치는 무인 코딩 워크플로에서 가장 위험도가 높은 단계 중 하나입니다.
Novita 문서 페이지로 워크플로를 구현하기에 충분한가요?
릴리즈된 템플릿 구문과 지원되는 Claude Code 메커니즘(헤드리스 실행, settings.json 구성, sandbox.git.clone, JSON 출력, 세션 resume)에는 충분합니다. 프로덕션 롤아웃을 위해서는 해당 런타임 주변에 자체 검토, 자격 증명, 정책 결정이 여전히 필요합니다.
