Claude Code 샌드박스 모범 사례는 한 가지 규칙에서 시작됩니다. Claude Code가 사람의 승인 없이 파일을 편집하고 명령을 실행할 수 있다면, 노트북이나 공유 CI 러너가 아닌 격리된 작업 공간에서 실행해야 한다는 것입니다. 이는 헤드리스 모드에서 더욱 중요합니다. 헤드리스 실행의 핵심은 에이전트가 사람이 "허용"을 클릭할 때까지 기다리지 않고 파일 편집, 셸 명령, 종속성 설치를 계속 수행할 수 있기 때문입니다. Novita의 Claude Code 샌드박스 가이드는 정확한 템플릿 명령어와 플래그의 진리값을 제공합니다. 이 글은 팀이 일반적으로 다음 단계로 필요로 하는 부분에 초점을 맞춥니다: 왜 Claude Code를 샌드박스 처리해야 하는지, 그렇지 않을 경우 어떤 문제가 발생할 수 있는지, 그리고 실제 워크플로우에 연결하기 전에 템플릿에 추가해야 할 프로덕션 제어 장치들입니다.
헤드리스 모드에서 Claude Code가 샌드박스를 필요로 하는 이유
Claude Code가 유용한 이유는 단순히 코드를 초안 작성하는 것 이상을 수행하기 때문입니다. 파일을 읽고, 파일을 편집하고, 셸 명령을 실행하며, 테스트 출력을 확인한 후 반복합니다. 이러한 능력이 바로 대화형 개발자 세션에서 무인 자동화로 전환할 때 샌드박스가 필요한 이유입니다.
로컬 터미널에서는 일반적으로 사람이 나쁜 아이디어를 조기에 발견합니다. 연 리포지토리를 볼 수 있고, 명령이 잘못된 디렉토리를 대상으로 할 때 알아차리며, 의심스러운 설치를 중단할 수 있습니다. 헤드리스 워크플로우에서는 이러한 자연스러운 확인 지점이 사라집니다. 에이전트는 제공된 지침과 환경만 볼 수 있습니다.
그렇기 때문에 올바른 비교는 "Claude Code 대 Claude Code 없음"이 아닙니다. “실제 머신 위의 Claude Code” 대 "격리된 실행 경계 내부의 Claude Code"입니다. 에이전트가 자율적으로 행동할 수 있게 되면 작업 공간은 안전 모델의 일부가 됩니다.
위험 표면은 상당히 구체적입니다:
| 위험 영역 | 샌드박스 없이 발생할 수 있는 문제 | 샌드박스가 변경하는 사항 |
|---|---|---|
| 리포지토리 범위 | 에이전트가 잘못된 리포지토리, 브랜치 또는 추적되지 않은 로컬 파일을 편집합니다 | 각 작업에 범위가 지정된 체크아웃, 알려진 기준 커밋 및 일회용 브랜치가 제공됩니다 |
| 셸 실행 | 명령이 호스트 머신 또는 공유 러너에서 실행됩니다 | 명령은 격리된 파일 시스템 및 프로세스 경계 내에 유지됩니다 |
| 종속성 설치 | npm, pip 등 패키지 설치가 호스트에서 임의의 스크립트를 실행합니다 |
패키지 설치는 정책과 로그가 있는 일회용 환경에서 이루어집니다 |
| 시크릿 | 에이전트가 볼 수 있는 환경 변수에 광범위한 개발자 또는 프로덕션 자격 증명이 포함될 수 있습니다 | 작업 범위의 시크릿을 샌드박스 세션으로 제한할 수 있습니다 |
| 검토 | 유일한 기록은 채팅 요약 또는 터미널 기록입니다 | Diff, 로그, stdout, stderr 및 아티팩트를 캡처하여 검토할 수 있습니다 |
Claude에 국한되지 않은 더 넓은 샌드박스 설계 체크리스트를 원한다면 코딩 에이전트 샌드박스: 에인트 생선 코드를 안전하게 실행하느 방법 및 격리된 샌드박스에서 Claude Code 또는 관리형 에이전트 실행을 읽어보세요. 여기서 차이점은 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가 검토 없이 멀티스텝 작업을 계속 진행할 수 있습니다.
올바른 대응은 실제 워크스테이션에서 이 플래그를 사용하고 결과를 기대하는 것이 아닙니다. 올바른 대응은 작업 공간, 리포지토리, 명령, 시크릿 및 네트워크 표면이 이미 제한된 샌드박스 내에서만 사용하는 것입니다. 샌드박스 경계가 폭발 반경을 줄이는 장소가 됩니다.
그렇기 때문에 이 설정을 문서화할 때 표현을 정확하게 유지해야 합니다. --dangerously-skip-permissions는 로컬 머신 편의를 위한 권장 사항이 아닙니다. 헤드리스 자동화를 위한 샌드박스 전용 운영 패턴입니다. 워크플로우가 여전히 Claude Code를 개발자 노트북, 공유 배스천 또는 프로덕션 유사 러너에서 실행한다면, 이를 대체해야 할 인프라 제어 장치를 추가하지 않고 인간 승인 프롬프트를 제거한 것입니다.
팀이 아직 해당 환경에서 패키지 설치를 신뢰할지 결정 중이라면, 이 글을 AI 에이전트 샌드박스에서 패키지 설치를 안전히 허용하는 방법 및 AI 에이전트 샌드박스 격리 경계 체크리스트와 함께 읽어보세요.
Novita의 claude-code 템플릿이 프로덕션 워크플로우에 매핑되는 방식
Novita 문서의 유용한 점은 추상적이지 않다는 것입니다. 프로덕션 워크플로우에 필요한 실제 메커니즘을 보여줍니다.
1. 헤드리스 -p 및 --print 모드
문서는 Claude Code를 비대화형 -p 모드로 사용하여 실행이 프롬프트를 받고, 결과를 출력하고, 종료할 수 있도록 합니다. 이는 헤드리스 자동화에 깔끔한 프로그래매틱 계약이 필요하기 때문에 중요합니다. 인간 세션에 연결된 장기 대화형 터미널을 원하지 않습니다. 시작하고, 관찰하고, 종료할 수 있는 작업 지향 실행을 원합니다.
이는 Claude Code CLI 문서에서 설명된 것과 동일한 구분입니다: 대화형 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
문서는 두 번째 유용한 패턴을 보여줍니다: Claude Code를 --output-format json으로 시작하고, 반환된 session_id를 파싱한 다음 --resume <session_id>로 계속하는 것입니다. 이것이 일회성 코드 편집을 프로그래매틱하게 관리할 수 있는 멀티스텝 워크플로우로 바꾸는 방법입니다.
이는 다음과 같은 작업에 적합합니다:
- 1단계: 리포지토리 검사 및 리팩토링 계획 생성
- 2단계: 동일한 세션을 재개하고 한 조각 구현
- 3단계: 다시 재개하여 후속 확인 또는 정리 실행
중요한 모범 사례는 "항상 resume 사용"이 아닙니다. 그것은 "의도적으로 resume 사용"입니다. 워크플로우가 연속성의 이점을 얻는다면 동일한 샌득박스에서 동일한 세션을 재개하세요. 작업이 독립적으로 검토 가능해야 한다면 상태를 암시적으로 전달하는 대신 새 샌드박스를 시작하세요.
5. 작업 후 워크스페이스 종료
Novita 문서는 예제를 샌드박스 종료로 마무리합니다. 이것이 바로 프로덕션에서 원하는 습관입니다. 헤드리스 코딩 에이전트는 조용히 오래된 워크스페이스, 백그라운드 프로세스 또는 남아 있는 자격 증명을 축적해서는 안 됩니다. 일회용 환경은 기록이 있는 수수께끼 머신보다 추론하기 쉽습니다.
해당 런타임 모델에 대한 더 큰 아키텍처 그림을 원한다면 Novita의 에이전트 샌드박스로 코딩 에이전트 구축이 적합한 참고 자료입니다.
Claude Code 샌드박스 모범 사례 체크리스트
다음 체크리스트는 문서 워크플로우의 프로덕션 버전입니다. 정확한 Novita 템플릿 메커니즘을 유지하면서 자동화된 파이프라인이 일반적으로 필요로 하는 제어 장치를 추가합니다.
- 작업당 하나의 샌드박스: 여러 관련 없는 작업을 하나의 장기 실행 Claude Code 환경에 연결하지 마세요. 신선한 워드박스는 시작 리포지토리 상태를 명확하게 하고, 종료를 쉽게 합니다.
- 범위 지정 Git 액세스: Claude Code가 리포지토리만 복제하고 검사해야 한다면 읽기 전용 토큰을 사용하세요. 브랜치를 �시해야 한면 해당 리포지토리와 해당 워크플로우로 범위가 제한된 토큰을 사용하세요. 상속된 개인 자격 증명은 피하세요.
- 샌드박스 패키지 설치: Claude Code는 실패한 빌드나 테스트를 재현하기 위해 종종 종속성이 필요합니다. 괜찮지만, 설치는 로그와 정책과 함께 샌드박스 내부에서 이루어져야 하며 오퍼레이터의 머신이 아닙니다. lockfile 변경 사항은 다른 코드 변경 사항처럼 검토하세요.
- 셸 출력을 증거로 취급: stdout, stderr, 종료 코드 및 실제 실행된 명령을 캡처하세요. 에이전트의 최종 요약은 유용하지만 자체적으로 검토에 충분하지 않습니다.
- 기본 프로덕션 시크릿 없음: 단기 또는 스테이징 전용 자격 증명을 선호하세요. 리포지토리를 읽고 명령을 실행할 수 있는 코딩 에이전트는 기본적으로 광범위한 클라우드 관리자 토큰이나 프로덕션 데이터베이스 자격 증명이 필요하지 않습니다.
- 결과뿐만 아니라 diff 검토: 헤드리스 성공은 Claude Code가 제공한 루프를 완료했다는 것만 의미합니다. 변경 사항이 올바르거나 배포 준비가 되었다는 의미는 아닙니다. 수정된 파일, 종속성 변경, 명령 출력 및 생성된 아티팩트를 검토하세요.
--dangerously-skip-permissions를 샌드박스 로컬로 유지: 이 설정에서 가장 중요한 운영 규칙입니다. 플래그는 격리되고 일회용인 작업 공간 내에 속합니다. 실제 머신에 대해 무인 Claude Code를 실행하기 위한 지름길이 되어서는 안 됩니다.- 실행과 릴리즈 분리: Claude Code가 패치를 검사, 편집, 테스트하고 준비하는 것은 허용될 수 있습니다. 그러나 병합, 게시 또는 배포 결정을 소유해서는 안 됩니다. 이러한 작업을 인간 또는 명시적 정책 게이트 뒤에 두세요.
- 의도적으로 재개: 작업이 연속성의 이점을 실제로 얻을 때
--resume <session_id>를 사용하세요. 재현성의 깨끗한 테스트가 필요하거나 한 작업이 다른 작업의 상태를 상속해서는 안 될 때는 샌드박스를 재설정하세요. - 전체 공급자 표면 비교: 이 워크플로우를 호스팅할 위치를 선택하는 경우, 환경이 Claude Code를 실행할 수 있는지 여부만 보지 마세요. 세션 수명 주기, 리포지토리 인체 공학, 로그, 일시 중지 및 재개 동작, 운영상의 트레이드오프를 비교하세요. 이 관점에 대해서는 E2B vs. Daytona: AI 에이전트 샌드박스 비교 및 Novita Sandbox: 원활한 호환성을 갖춘 E2B Pro의 비용 효율적인 대안이 관련 비교 자료입니다.
피해야 할 일반적인 실수
가장 일반적인 Claude Code 샌드박스 실수는 개념적이기보다 운영적인 경우가 많습니다.
실수 1: 문서 예제를 완전한 프로덕션 정책으로 취급
문서는 claude-code 템플릿을 올바르게 실행하는 방법을 보여줍니다. 완전한 검토, 네트워크 또는 시크릿 관리 정책이 되려고 하지 않습니다. 구문과 런타임 메커니즘에 사용하고, 그 위에 자체 리포지토리 및 승인 경계를 추가하세요.
실수 2: 개발자 워크스테이션을 "샌드박스"로 재사용
노트북의 터미널에서 Claude Code를 실행하는 것은 유효한 개발자 워크플로우입니다. 무인 자동화를 위한 일회용 격리 런타임과 동일하지 않습니다.
실수 3: 세션 상태를 암시적으로 남김
--resume을 사용한다면 어떤 상태를 전달하고 있는지, 왜 그런지 알고 있어야 합니다. "확실하지는 않지만 편리해서"라면 더 어려운 검토 문제를 만들고 있는 것입니다.
실수 4: 실제 시크릿을 탐색적 코드 작업과 혼합
샌드박스는 폭발 반경을 줄이기 위해 있습니다. 작업 공간이 여전히 광범위한 자격 증명으로 프로덕션 시스템에 도달할 수 있다면 가장 중요한 경계를 약화시킨 것입니다.
실수 5: 성공적인 실행을 증거보다 더 신뢰
에이전트는 작업을 완료할 수 있지만 여전히 잘못된 변경을 하거나, 잘못된 파일을 수정하거나, 원하지 않는 종속성을 추가할 수 있습니다. 내러티브 요약뿐만 아니라 diff와 로그를 검토하세요.
FAQ
--dangerously-skip-permissions는 Claude Code에 안전 기능이 전혀 없다는 뜻인가요?
세션 내에서 대화형 승인을 더 이상 기다리지 않는다는 뜻입니다. 헤드리스 워크플로우에서 의도된 안전 계층은 세션 주변의 샌드박스 경계입니다: 격리된 리포지토리, 제한된 자격 증명, 샌드박스 내부의 명령 실행, 캡처된 로그, 병합 전 인간 검토입니다.
모든 Claude Code 자동화는 신선한 샌드박스에서 실행되어야 하나요?
신선한 샌드박스는 독립적인 작업에 가장 깔끔한 기본값입니다. Resume 기반 워크플로우는 동일한 멀티스텝 작업이 연속성을 필요로 할 때 유용하지만, 상태는 의도적이고 검토 가능해야 하며 우발적이어서는 안 됩니다.
Claude Code가 샌드박스에서 패키지를 안전하게 설치할 수 있나요?
더 안전하게 만들 수는 있지만 자동으로 안전하지는 않습니다. 패키지 정책, lockfile 검토, 범위 지정 네트워크 액세스 및 감사 로그를 사용하세요. 패키지 설치는 무인 코딩 워크플로우에서 가장 위험한 단계 중 하나입니다.
Novita 문서 페이지로 워크플로우를 구현하기에 충분한가요?
릴리즈된 템플릿 구문과 지원되는 Claude Code 메커니즘(헤드리스 실행, settings.json 구성, sandbox.git.clone, JSON 출력, 세션 재개)에는 충분합니다. 프로덕션 롤아웃을 위해서는 여전히 해당 런타임에 대한 자체 검토, 자격 증명 및 정책 결정이 필요합니다.
