Claude Code 스타일 또는 관리형 코딩 에이전트를 샌드박스에서 실행하려면 각 에이전트에 범위가 지정된 작업 공간, 명시적인 파일 권한, 제어된 셸 실행, 네트워크 및 패키지 정책, 명확한 비밀 경계, 지속적인 로그, 캡처된 아티팩트, 그리고 변경 사항이 병합되거나 배포되기 전에 사람이 검토하도록 해야 합니다. 에이전트는 여전히 코드를 읽고, 파일을 편집하고, 의존성을 설치하고, 테스트를 실행하고, 패치를 생성할 수 있지만, 그 주변 환경이 에이전트가 접근할 수 있는 대상, 가져올 수 있는 대상, 볼 수 있는 자격 증명, 그리고 사람이 다음 단계를 승인해야 하는 시점을 결정합니다.
격리해야 할 것
코딩 에이전트는 단순히 저장소에 연결된 챗봇이 아닙니다. 파일을 편집하고 명령을 실행할 수 있게 되면 언어 모델 추론이 루프에 포함된 주니어 빌드 워커와 유사해집니다. 해당 워커는 npm test를 실행하거나, 생성된 파일을 검사하거나, 개발 서버를 시작하거나, 오류 메시지가 제안하는 패키지 설치를 시도할 수 있습니다. 작업 공간이 노트북, 공유 CI 러너, 또는 장기 실행 프로덕션 유사 VM인 경우, 영향 범위가 너무 넓습니다.
격리 대상은 에이전트 작업 루프 전체입니다.
- 에이전트가 읽거나 수정할 수 있는 저장소 체크아웃 및 브랜치.
- 에이전트가 쓸 수 있는 파일 시스템 경로.
- 자동으로 실행할 수 있는 명령.
- 승인이 필요한 명령.
- 에이전트가 도달할 수 있는 패키지 레지스트리, 도메인 및 API.
- 세션에 노출된 자격 증명.
- 검토를 위해 보존된 로그, diff, 테스트 출력, 스크린샷 및 아티팩트.
- 성공, 실패 또는 시간 초과 후의 정리 동작.
Claude Code 및 기타 관리형 코딩 에이전트 제품에는 자체 권한 시스템이 포함될 수 있습니다. 예를 들어 Anthropic의 Claude Code 문서는 허용 및 거부된 도구, 승인 동작, 로컬 사용을 위한 샌드박싱 지침에 대한 권한 설정을 설명합니다. 이러한 제어를 전체 경계가 아닌 하나의 계층으로 취급하십시오. 더 강력한 설계는 에이전트를 격리된 런타임 내부에 배치한 다음 해당 런타임 내에서 도구 권한을 적용합니다.
참조 아키텍처
실용적인 샌드박스 에이전트 워크플로는 네 가지 계층으로 구성됩니다.
| 계층 | 목적 | 일반적인 제어 |
|---|---|---|
| 에이전트 컨트롤러 | 작업 계획 및 도구 호출 결정 | 모델/도구 권한, 승인 모드, 작업 프롬프트 |
| 샌드박스 런타임 | 명령이 실행되는 작업 공간 호스팅 | 격리된 파일 시스템, 프로세스 제한, 수명 주기 제어 |
| 정책 게이트웨이 | 허용되는 작업 결정 | 명령 규칙, 네트워크 이그레스 규칙, 패키지 정책, 비밀 범위 |
| 검토 표면 | 사람이 결과를 검사할 수 있도록 함 | Diff, 로그, 테스트 결과, 아티팩트, 풀 리퀘스트 |
이러한 계층을 분리하여 유지하십시오. 프롬프트 인젝션으로 에이전트 컨트롤러가 손상되더라도 샌드박스 런타임과 정책 게이트웨이는 발생할 수 있는 작업을 제한해야 합니다. 패키지 설치가 예상치 못한 코드를 가져오는 경우 네트워크 및 아티팩트 로그를 통해 이를 확인할 수 있어야 합니다. 에이전트가 그럴듯한 패치를 생성하는 경우에도 검토 표면은 정확히 무엇이 변경되었고 어떤 테스트가 실행되었는지 보여주어야 합니다.
개념적 정책 객체는 다음과 같을 수 있습니다.
workspace:
mode: ephemeral
repo_ref: pull-request-branch
writable_paths:
- /workspace/project
readonly_paths:
- /workspace/reference
commands:
auto_allow:
- git status
- npm test
- npm run lint
- pytest
require_approval:
- npm install
- pip install
- docker build
- git push
deny:
- rm -rf /
- curl ... | sh
network:
default: deny
allow:
- registry.npmjs.org
- pypi.org
- files.pythonhosted.org
secrets:
expose:
- READ_ONLY_PACKAGE_TOKEN
deny:
- PRODUCTION_DATABASE_URL
- CLOUD_ADMIN_TOKEN
artifacts:
capture:
- git diff
- test-results/
- screenshots/
- command-log.jsonl
이는 SDK 예제가 아닙니다. 정확한 정책 형식은 에이전트 프레임워크와 샌드박스 제공자에 따라 다릅니다. 중요한 점은 권한이 모델의 자유 형식 추론 외부에서 표현된 다음 런타임 또는 오케스트레이션 계층에 의해 시행되어야 한다는 것입니다.
작업 공간 및 저장소 설정
모든 에이전트 실행은 깨끗한 작업 공간에서 시작하십시오. 관리형 에이전트는 고의적인 이유가 없는 한 개발자의 셸 기록, SSH 에이전트, dotfiles, 클라우드 CLI 로그인 또는 추적되지 않은 로컬 파일을 상속해서는 안 됩니다.
저장소 작업의 경우 전용 체크아웃을 사용하십시오.
- 작업에 필요한 저장소만 복제하거나 마운트합니다.
- 기본 브랜치를 편집하는 대신 새 작업 브랜치를 체크아웃합니다.
- 기본 커밋을 고정하여 검토가 시작점을 재현할 수 있도록 합니다.
- 의존성 캐시를 쓰기 가능한 소스 경로와 분리합니다.
- 생성된 아티팩트는 의도된 diff의 일부가 아닌 한 소스 트리 외부에 저장합니다.
브랜치 격리는 중요합니다. 코딩 에이전트는 종종 하나의 접근 방식에 정착하기 전에 여러 가지 방법을 시도하기 때문입니다. 깨끗한 작업 브랜치는 검토자에게 임시 실험이 포함된 혼합 작업 공간 대신 일반적인 풀 리퀘스트 diff를 제공합니다. 에이전트가 참조 구현과 비교해야 하는 경우 해당 참조를 읽기 전용으로 마운트하십시오.
장기 실행 관리형 에이전트의 경우 샌드박스가 임시인지, 일시 중지되는지, 스냅샷되는지 결정하십시오. 임시 작업 공간은 추론하기 더 쉽습니다. 스냅샷과 일시 중지/재개는 긴 작업, 브라우저 세션 및 비용이 많이 드는 설정 단계에 유용하지만, 여전히 명확한 감사 추적(스냅샷이 생성된 시기, 어떤 파일이 있었는지, 어떤 자격 증명을 사용할 수 있었는지)을 보존해야 합니다.
파일 시스템 권한
파일 시스템 범위는 "에이전트가 전체 머신을 읽을 수 있음"보다 좁아야 합니다. 대부분의 코딩 작업에는 다음이 필요합니다.
- 저장소 작업 공간에 대한 읽기/쓰기 액세스.
- 선택된 작업 컨텍스트, 픽스처 또는 문서에 대한 읽기 전용 액세스.
- 빌드 출력 및 스크래치 파일을 위한 임시 디렉터리.
- 호스트 홈 디렉터리, 관련 없는 저장소, 클라우드 자격 증명, 브라우저 프로필 또는 프로덕션 데이터 덤프에 대한 액세스 금지.
쓰기 권한은 특별히 주의해야 합니다. 저장소를 편집할 수 있는 코딩 에이전트는 스크립트, 테스트, lockfiles, CI 구성 및 배포 파일도 편집할 수 있습니다. 이는 작업에 정확히 필요한 것일 수 있지만 검토에서 확인 가능해야 합니다. .github/workflows/, 배포 매니페스트 또는 패키지 게시 구성과 같은 민감한 경로의 경우 더 강력한 승인 단계 또는 사람이 소유한 최종 검토가 필요합니다.
작업 범위가 좁은 경우 파일 허용 목록을 사용하십시오. 예를 들어, 문서화 에이전트는 docs/와 생성된 미리보기 디렉터리만 필요할 수 있습니다. 의존성 업그레이드 에이전트는 package.json, lockfiles 및 테스트 스냅샷이 필요할 수 있습니다. 광범위한 리팩터링은 더 넓은 액세스가 필요하지만, 검토는 더 큰 diff와 더 완전한 테스트를 예상해야 합니다.
셸 실행 정책
셸 액세스는 코딩 에이전트가 유용해지면서도 위험해지는 지점입니다. 테스트 실행, 코드 포맷팅, 빌드 오류 검사, 수정 확인을 위해 명령 실행이 필요합니다. 하지만 모든 명령을 멈춤 없이 실행할 수 있는 무제한 권한이 필요하지는 않습니다.
좋은 셸 정책은 세 가지 버킷으로 구성됩니다.
| 버킷 | 예시 | 중요한 이유 |
|---|---|---|
| 자동 허용 | git status, npm test, pytest, go test ./..., npm run lint |
일반적인 편집-테스트 루프를 빠르게 유지 |
| 승인 필요 | 패키지 설치, 마이그레이션, 장기 실행 서비스, 외부 CLI, git push |
상태, 비용 또는 네트워크 위험이 변경되는 곳에 마찰 추가 |
| 거부 | 파괴적인 호스트 명령, 자격 증명 덤프, 안전하지 않은 셸 파이핑, 작업 공간 외부 쓰기 | 위임해서는 안 되는 작업 차단 |
명령 텍스트 일치에만 의존하지 마십시오. 에이전트는 스크립트, 패키지 관리자 후크 또는 중첩 셸을 통해 명령을 실행할 수 있습니다. 위험이 높은 환경의 경우 명령 정책을 런타임 수준의 파일 시스템 경계, 리소스 제한 및 네트워크 제어와 결합하십시오.
장기 실행 명령에는 시간 초과 동작이 필요합니다. 테스트 서버, 브라우저 자동화 실행 또는 빌드 와처는 에이전트가 이동한 후에도 활성 상태로 남아 있을 수 있습니다. 프로세스 ID, stdout, stderr, 종료 상태, 런타임 및 종료 이유를 캡처하십시오. 명령이 미리보기 포트를 여는 경우 포트 매핑을 기록하고 정리 중에 종료하십시오.
패키지 설치 및 네트워크 이그레스
패키지 설치는 에이전트 작업 공간의 가장 유용한 기능 중 하나이면서 위험이 발생하기 쉬운 부분 중 하나입니다. 코딩 에이전트는 Stack Overflow 답변, README 또는 모델이 생성한 계획이 제안했기 때문에 패키지를 설치할 수 있습니다. 이는 의존성 그래프를 변경하고, 설치 스크립트를 실행하며, 외부 레지스트리에 도달할 수 있습니다.
구현 가이드 및 프로덕션 워크플로의 경우 기본 거부 네트워크 자세로 시작한 다음 작업에 필요한 것을 허용하십시오.
- npm 또는 PyPI와 같은 패키지 레지스트리(가급적 레지스트리 미러 또는 캐시를 통해).
- 저장소 및 서브모듈에 필요한 소스 호스트.
- 작업에 필요한 문서 도메인.
- 샌드박스에 올바른 데이터 분류가 있는 경우에만 내부 API.
모든 에이전트에게 기본적으로 광범위한 아웃바운드 인터넷을 제공하지 마십시오. 연구 또는 브라우저 자동화를 위해 광범위한 액세스가 필요한 경우 해당 실행을 코드 수정 실행과 분리하고 아티팩트에 그에 따라 레이블을 지정하십시오.
패키지 설치의 경우 다음을 기록하십시오.
- 패키지 관리자 명령.
- 레지스트리 호스트.
- Lockfile 변경 사항.
- 가능한 경우 다운로드된 패키지 이름 및 버전.
- 실행된 설치 스크립트.
- 사람이 설치를 승인했는지 여부.
이렇게 해도 임의의 패키지가 안전해지는 것은 아닙니다. 변경 사항을 검토 가능하게 만듭니다.
비밀 경계
비밀은 작업에 범위가 지정되고, 수명이 짧으며, 기본적으로 없어야 합니다. 가장 안전한 샌드박스는 모델이 비밀을 절대 노출하지 않겠다고 약속하는 것이 아니라, 작업에 실제로 필요한 경우가 아니면 비밀이 존재하지 않는 샌드박스입니다.
다음 기본값을 사용하십시오.
- 에이전트 작업 공간에 프로덕션 데이터베이스 자격 증명 없음.
- 클라우드 관리자 토큰 없음.
- 개인 SSH 키 또는 개발자 머신 자격 증명 없음.
- 가능한 경우 읽기 전용 자격 증명.
- 패키지 읽기, 테스트 픽스처 또는 스테이징 전용 API를 위한 별도 토큰.
- 아티팩트가 공유되기 전에 로그에서 비밀 편집.
에이전트가 외부 서비스를 호출해야 하는 경우 좁은 토큰을 제공하고 어떤 도구 또는 명령이 이를 사용했는지 기록하십시오. 에이전트가 편집할 수 있는 파일에 광범위한 자격 증명을 배치하지 마십시오. 환경 변수는 편리하지만 명령에 의해 출력되거나, 로그에 포함되거나, 생성된 파일에 복사될 수 있습니다. 에이전트 프로세스에 노출된 것으로 간주하십시오.
로그, 아티팩트 및 감사 추적
인간 검토는 검토자가 무슨 일이 일어났는지 볼 수 있을 때만 유용합니다. 샌드박스 코딩 에이전트 실행은 최종 패치 이상을 보존해야 합니다.
최소한 다음을 캡처하십시오.
- 작업 프롬프트 또는 지침 요약.
- 기본 커밋 및 브랜치.
- 도구가 기록할 수 있는 경우 읽고 쓴 파일.
- 타임스탬프, 작업 디렉터리, 종료 상태, stdout 및 stderr가 포함된 실행된 명령.
- 패키지 설치 및 네트워크 액세스 요약.
- 테스트 및 빌드 결과.
- 생성된 파일, 스크린샷, 보고서 또는 미리보기 링크.
- 최종 diff.
샌드박스보다 오래 지속되는 검토 표면에 로그를 저장하십시오. 실행 직후 샌드박스가 파괴되더라도 풀 리퀘스트, CI 아티팩트 저장소 또는 에이전트 플랫폼 기록에서 증거를 계속 사용할 수 있어야 합니다.
관리형 에이전트를 사용하는 팀의 경우 이 감사 추적은 에이전트 성능을 비교하는 데도 도움이 됩니다. 실패가 누락된 의존성, 거부된 명령, 불명확한 프롬프트, 불안정한 테스트 또는 실제 코드 문제로 인한 것인지 확인할 수 있습니다.
정리 및 재설정
샌드박스 정리는 보안 및 비용 제어이지 단순한 유지 관리가 아닙니다. 실행이 끝나면:
- 백그라운드 프로세스를 중지합니다.
- 노출된 포트를 닫습니다.
- 작업 범위의 토큰을 취소합니다.
- 필요한 아티팩트를 내보냅니다.
- 검토의 일부가 아닌 임시 파일을 삭제합니다.
- 실행 유형에 따라 샌드박스를 파괴, 일시 중지 또는 스냅샷합니다.
임시 재설정은 신뢰할 수 없거나 탐색적인 작업에 가장 깔끔한 기본값입니다. 장기 실행 에이전트의 경우 알려진 양호한 설정 단계 이후에만 스냅샷을 생성하고, 임의의 에이전트 활동 이후에는 스냅샷을 생성하지 마십시오. 실패한 실행을 조사해야 하는 경우 명확한 만료 시간과 함께 샌드박스 또는 스냅샷을 보존하십시오.
Novita Agent Sandbox의 역할
Novita Agent Sandbox는 코드가 개발자 노트북이나 공유 호스트가 아닌 격리된 클라우드 작업 공간 내에서 실행되는 AI 에이전트 실행 워크플로를 위해 설계되었습니다. Novita의 Sandbox 문서는 이 가이드의 패턴에 매핑되는 핵심 기본 요소(샌드박스 수명 주기 관리, 파일 시스템 작업, 명령 실행, 템플릿, 에이전트 워크로드를 위한 런타임 관리)를 설명합니다.
따라서 Novita는 모델 API와 함께 실행 환경이 필요한 코딩 에이전트, 데이터 분석, 브라우저 에이전트, 평가 또는 장기 실행 에이전트 워크플로를 구축하는 팀에 적합합니다. 그러나 경계를 명확히 유지하십시오. 이 문서는 Claude Code 스타일 및 관리형 코딩 에이전트를 위한 일반적인 구현 패턴입니다. 공식 Claude Code 통합, 파트너십 또는 모든 관리형 에이전트 제품과의 보편적인 호환성을 주장하는 것이 아닙니다.
Novita 기반 워크플로를 설계하는 경우 정확한 릴리스된 API 표면에 대해 제품 문서를 사용하고 정책 계층을 명시적으로 유지하십시오. 샌드박스는 격리된 실행 작업 공간을 제공할 수 있습니다. 애플리케이션은 여전히 명령 승인, 네트워크 정책, 비밀 범위, 아티팩트 보존 및 인간 검토 게이트를 결정해야 합니다.
보안 검토 체크리스트
코딩 에이전트가 장난감 저장소 이상으로 실행되도록 허용하기 전에 이 체크리스트를 사용하십시오.
| 질문 | 확인할 사항 |
|---|---|
| 격리 경계는 무엇인가요? | 전용 작업 공간, 프로세스 제한, 파일 시스템 분리 및 명확한 제공자 문서 |
| 에이전트가 읽을 수 있는 것은 무엇인가요? | 기본적으로 저장소 전용 액세스, 호스트 홈 디렉터리 없음, 관련 없는 저장소 없음 |
| 에이전트가 쓸 수 있는 것은 무엇인가요? | 쓰기 가능한 소스 경로가 명시적임. 민감한 구성 경로는 추가 검토 필요 |
| 어떤 명령이 자동으로 실행되나요? | 테스트 및 포맷팅 명령은 허용됨. 상태 변경 명령은 승인 필요 |
| 어떤 네트워크 액세스가 존재하나요? | 기본 거부 또는 범위가 지정된 이그레스. 패키지 레지스트리 및 문서 도메인은 의도적임 |
| 패키지 설치는 어떻게 처리되나요? | Lockfile 변경 사항, 레지스트리 호스트 및 설치 스크립트가 기록됨 |
| 어떤 비밀이 존재하나요? | 작업 범위, 수명이 짧고, 최소 권한 자격 증명만 |
| 로그는 어떻게 되나요? | 명령, 출력, diff 및 아티팩트가 샌드박스 정리 후에도 유지됨 |
| 정리는 어떻게 적용되나요? | 백그라운드 프로세스, 포트, 토큰 및 임시 파일이 닫히거나 취소됨 |
| 병합 또는 배송을 승인하는 사람은 누구인가요? | 인간 검토자가 코드, 테스트, 보안에 민감한 파일 및 생성된 아티팩트를 확인함 |
가장 중요한 규칙은 간단합니다. "에이전트가 권한을 요청했다"는 것과 "시스템이 경계를 적용했다"는 것을 혼동하지 마십시오. 모델은 수행하려는 작업을 설명하는 데 도움이 될 수 있습니다. 런타임 및 정책 계층은 수행할 수 있는 작업을 결정해야 합니다.
FAQ
Claude Code를 샌드박스에서 실행할 수 있나요?
네, Claude Code 스타일 에이전트를 범위가 지정된 작업 공간 내에 배치하고 그 주변에 파일 시스템, 셸, 네트워크, 비밀, 로깅 및 검토 정책을 적용하는 설정이 있다면 가능합니다. 프로덕션 또는 민감한 저장소의 경우 로컬 권한 프롬프트만으로는 충분하지 않다고 가정하지 마십시오.
코딩 에이전트 격리에 컨테이너로 충분한가요?
때로는 가능하지만, 답변은 위협 모델에 따라 다릅니다. 컨테이너는 반복 가능한 빌드와 의존성 분리에 유용할 수 있지만, 보안에 민감한 워크로드는 컨테이너를 완전한 샌드박스 경계로 취급하기 전에 커널 경계, 호스트 마운트, 네트워크 기본값, 런타임 권한 및 제공자 문서를 평가해야 합니다.
에이전트가 패키지를 설치하도록 허용해야 하나요?
허용할 수 있지만, 패키지 설치는 제어된 공급망 이벤트로 처리해야 합니다. 레지스트리 허용 목록 또는 미러, lockfile 검토, 설치 스크립트 로깅, 그리고 원격 코드를 가져와 실행하는 새로운 의존성 또는 명령에 대한 승인을 선호하십시오.
병합 전에 인간 검토자는 무엇을 확인해야 하나요?
최종 diff, 실행된 명령, 실행된 테스트, 패키지 및 lockfile 변경 사항, 수정된 CI/배포 파일, 생성된 아티팩트, 그리고 거부되거나 승인이 필요한 작업을 검토하십시오. 보안에 민감한 저장소의 경우 변경 사항의 일부로 샌드박스 정책 자체를 검토하십시오.
Novita Agent Sandbox가 Claude Code와 공식적으로 통합되나요?
이 문서는 그러한 주장을 하지 않습니다. Novita Agent Sandbox는 에이전트 워크플로를 위한 격리된 실행 기본 요소를 제공하는 반면, Claude Code 및 관리형 에이전트 제품에는 자체 제품별 인터페이스와 권한 모델이 있습니다. 실행 가능한 명령을 게시하기 전에 현재 제품 문서에 대해 정확한 통합 경로를 확인하십시오.
