에이전트 격리 모범 사례: 샌드박싱(비공개 베타)

사이버 검증 프로그램의 고객을 위해 API에서 새로운 샌드박스 탈출 분류기를 제공하여 오용을 모니터링하고 줄입니다. 이 문서에서는 자율 에이전트가 강력한 격리가 필요한 이유, 참조 설계가 이들을 격리하는 방법, 네트워크 액세스가 필요한 작업의 범위를 정하고 감독하는 방법을 설명합니다.

사용 가능한 모든 리소스의 개요를 보려면 에이전트 격리 모범 사례: 시작하기(비공개 베타)를 참조하세요.

자신의 샌드박스를 구축하는 경우, 이러한 속성들이 참조 설계가 제공하는 것입니다. 이 문서의 나머지 부분에서는 이를 달성하는 한 가지 방법을 설명합니다.

자율 에이전트를 강력한 샌드박스에서 실행하고, 해당 샌드박스의 프로세스가 여전히 야기할 수 있는 부작용을 생각해 보세요. 최첨단 모델은 제한을 우회하는 창의적인 경로를 찾는 데 점점 더 능숙해지고 있습니다. 이들을 효과적인 취약점 사냥꾼으로 만드는 동일한 속성은 자신의 실행 환경에 대해 예상치 못한 조치를 취할 수 있음을 의미합니다. 이는 가설이 아닙니다. Anthropic은 약한 제약을 우회하여 작업을 완료하는 모델의 예를 발표했습니다(Claude를 제품 전체에서 격리하는 방법 참조).

구체적으로, 베어 Docker/runc에서 자율 취약점 발견 에이전트를 실행하지 마세요. 특히 --privileged 또는 호스트 네트워킹을 사용하지 마세요. 표준 컨테이너는 호스트 커널을 공유하므로 컨테이너 내의 커널 익스플로잇은 호스트 손상입니다. 대상 코드와 호스트 사이에 하드웨어 가상화 커널을 배치하는 것을 권장합니다. 이는 에이전트를 가상 머신에서 실행하는 것을 의미합니다. 불가능한 경우 다른 것을 보유하지 않는 전용 베어메탈 호스트를 사용하세요. 자신의 샌드박스를 구축하는 경우 Linux에서는 Firecracker, Windows에서는 Hyper-V, macOS에서는 Hypervisor 프레임워크 기반 VM을 권장합니다. 참조 설계는 Firecracker를 사용합니다.

샌드박스에서 모든 송신을 차단합니다. 에이전트는 자격증명을 추가하고 샌드박스 외부에서 실행되는 프록시를 통해서만 모델 API에 도달하므로 샌드박스는 API 호스트로의 직접 경로가 필요하지 않습니다. 실행이 시작되기 전에 모든 도구, 패키지 및 종속성을 설치하여 실행 중에 아무것도 가져올 필요가 없도록 하세요.

루프에 인간이 있는 대화형 사용은 일반적으로 위험이 적지만, 여전히 샌드박스를 권장합니다. 노트북의 Claude Code에서 에이전트를 대화형으로 구동하는 경우, 모든 도구 사용을 검토하거나(수동 모드), 자동 모드 권한 분류기에 의존하고 리포지토리 외부에 도달하는 모든 작업을 인간이 승인하도록 하세요. 자동 모드는 일상적인 권한 프롬프트를 제거합니다. 읽기 및 작업 디렉토리 편집을 자동으로 승인하고 다른 모든 것을 배경 분류기로 보냅니다. 이 분류기는 파괴적이거나 되돌릴 수 없거나 작업 범위를 벗어난 작업을 차단하는 것을 목표로 합니다. 최선의 노력입니다. 놓칠 수 있으며, 보안 작업에서는 일부 정당한 단계를 거부할 수도 있습니다. 자동 모드는 작동 방식, 예상할 수 있는 것, 환경에 맞게 구성하는 방법을 설명합니다.

~/.aws, ~/.ssh 또는 .env와 같은 자격증명을 포함하는 경로를 에이전트의 환경에 마운트하지 마세요. 에이전트 자신의 모델 호출이 사용하는 자격증명도 마찬가지입니다. 이를 샌드박스 외부에 유지하고, 에이전트가 읽을 수 없는 프록시가 각 요청에 이를 추가하도록 하세요(자격증명 프록시 참조). 에이전트를 이메일, 클라우드 스토리지 또는 프로덕션 인프라와 같은 외부 상태에 대한 쓰기 액세스 권한이 있는 MCP 서버 또는 도구에 연결하지 마세요.

이것은 위의 지침을 실행에 옮기는 한 가지 패턴입니다. 설정 단계는 아웃바운드 인터넷 액세스와 모든 도구 호출을 승인하는 루프의 인간을 가집니다. 이 단계에서 에이전트는 종속성을 가져오고, 대상을 구축하고, 사양 문서에서 샌드박스를 설정합니다. 공격 단계는 일반 인터넷 액세스가 없습니다. 모든 송신은 참여에서 명명된 호스트만 허용하는 허용 목록 프록시를 통해 이루어지므로 프록시는 범위도 적용합니다. 모델 호출은 별도의 자격증명 프록시를 통해 이루어집니다. 그러면 에이전트는 무인으로 대상을 조사할 수 있습니다. 프록시는 에이전트 자신의 트래픽을 포함합니다. 네트워크된 대상이 에이전트를 대신하여 보내는 트래픽은 포함하지 않습니다.

에이전트가 반복적으로 필요로 하는 종속성을 설정 이미지에 구워서 공격 단계 실행이 인터넷 액세스를 전혀 필요로 하지 않도록 하세요. 자격증명을 대상별로 범위를 지정하여 한 대상에서 작업하는 에이전트가 다른 대상에 대해 이를 사용할 수 없도록 하세요. 공격 단계 중에 샌드박스 내에서 Claude Code의 자동 모드를 켜두고 샌드박스를 분류기에 설명하세요. 자동 모드를 참조하세요.

모든 에이전트에 명시적 예산을 제공하여 의도된 테스트를 초과하는 실행이 누군가 알아차릴 때가 아니라 자체적으로 중지되도록 하세요. 모든 에이전트에 하드 턴 제한을 적용하세요. 에이전트가 이를 소진하면 실행을 종료하고 자동으로 더 많은 턴을 부여하지 마세요. 더 높은 제한으로 다시 시작하는 것은 사람이 계속하기로 결정하는 시점입니다. 시간으로도 실행을 제한하세요. 시간 제한을 초과하는 세션을 같은 방식으로 종료하세요. 실행은 최종이며 절대 재개되지 않으며, 제한이 장기 실행 명령의 중간에 도달해도 에이전트 프로세스는 중지됩니다. 제한이 읽을 수 없는 값으로 설정된 경우 무제한으로 실행하는 대신 시작을 거부하세요. 참여에 대해 의도적으로 제한을 설정하고 관대한 기본값을 수락하지 마세요. 에이전트 트랜스크립트의 오프라인 모니터링의 모니터링 주기와 쌍을 이루어 긴 배치가 끝에서만이 아니라 1~2시간마다 검토되도록 하세요. 배치를 중지하지 않고 단일 에이전트를 중지하는 방법을 알아두세요. Docker 기반 설정에서는 docker rm -f <agent-container>입니다. 오케스트레이터는 해당 실행을 실패로 기록하고 나머지 배치를 계속해야 합니다.

더 많은 지침을 보려면 두 가지 Anthropic 리소스를 읽으세요. AI 에이전트를 안전하게 배포하기는 격리 옵션, 자격증명 프록싱 및 파일 시스템 강화를 다룹니다. 엔지니어링 회고 Claude를 제품 전체에서 격리하는 방법은 이러한 동일한 메커니즘이 프로덕션에서 실행될 때 무엇이 작동했고 무엇이 작동하지 않았는지를 다룹니다.

샌드박스는 에이전트가 도달할 수 있는 것을 제한합니다. 펜테스팅, 레드 팀 및 네트워크 액세스가 필요한 기타 참여의 경우, 아래의 관행은 에이전트에게 요청되고 허용되는 것을 제한합니다. 이들은 대상과 팀에 따라 다르므로 도구는 대부분을 자동으로 배치할 수 없습니다.

실행 전에 에이전트에게 범위 내 대상, 허용된 작업, 네트워크 경계 위치 및 범위 외 항목을 알려주세요. 각 제약을 의도로 표현하세요("10.0.3.0/24 외부의 호스트에 액세스하지 마세요"). 환경에 대한 주장이 아니라("인터넷에 도달할 수 없습니다"), 환경이 잘못 구성된 경우에도 지시사항이 유지되도록 하세요. 샌드박스된 로컬 작업에도 이를 수행하세요. 샌드박스가 이를 차단하더라도 에이전트에게 인터넷 액세스를 사용하지 말라고 알려주세요. 자동 모드의 분류기에 제공하는 설명은 다른 것입니다. 이는 머신에 대한 사실을 명시합니다(자동 모드 참조).

가능한 경우 에이전트를 위에서 설명한 동일한 격리 내에서 실행하고 범위 내 대상으로만 송신을 허용 목록에 추가하세요(송신 허용 목록 참조). 에이전트는 허용 목록이 아닌 자격증명 프록시를 통해 모델 API에 도달합니다. 사용 가능한 경우 참여를 프로덕션에서 분리된 스테이징 또는 복제 환경으로 지정하세요.

에이전트에게 액세스 프록시 또는 정의된 도구 집합과 같이 관찰할 수 있는 것을 통해 대상 시스템에 액세스하도록 하세요. 에이전트가 대상에 대한 일반 액세스 권한으로 자신의 도구를 작성하도록 하지 마세요. 사용자 정의 하네스에서 읽기 전용 도구를 상태를 변경하는 도구와 분리하고 두 번째 그룹을 더 자세히 감독하세요. 위험한 명령을 제안할 때 분석하고 거부하거나 사람에게 에스컬레이션하는 것을 고려하세요.

엔지니어가 각 실행을 실행할 때 지켜보고, 도구 호출과 네트워크 활동을 따르고, 즉시 실행을 중지할 수 있기를 권장합니다. 에이전트는 기계 속도로 작동하므로 라이브 관찰은 작업 실행 전에 작동하는 제어(네트워크 허용 목록, 중개된 도구 및 상태 변경 작업 검토)를 보완합니다. 이를 대체하지는 않습니다. 연속 주의가 비실용적인 긴 또는 자율 실행의 경우 소프트웨어에서 지속적으로 모니터링하세요(에이전트 트랜스크립트의 오프라인 모니터링 참조).

범위를 벗어난 작업이 OT/ICS, 의료 또는 에너지 시스템과 같은 중요 서비스의 안전이나 가용성을 위협할 수 있는 실시간 프로덕션 시스템에 대해 자율 에이전트를 실행하지 마세요. 이는 이미 이러한 시스템의 인간 주도 테스트의 표준이며 여기에도 동등하게 적용됩니다. 복제본, 테스트베드 또는 디지털 트윈에 대해 테스트하거나 계획된 중단 중에 테스트하세요. 실시간 액세스가 불가피한 경우 에이전트를 수동 또는 읽기 전용 활동으로 제한하고 사람이 모든 상태 변경 단계를 수행하도록 하세요.

호스트에서 실제 참여를 실행하기 전에 아래의 두 단계로 샌드박스를 테스트하세요. 첫 번째 실제 사용 전에 이를 수행하고, 모델이나 샌드박스를 변경할 때마다 다시 수행하세요. 샌드박스 변경에는 새 호스트, 하이퍼바이저 또는 컨테이너 런타임의 새 버전, 다른 네트워크 또는 프록시 설정, 편집된 컨테이너 또는 구성 작성이 포함됩니다.

호스트의 대화형 Claude Code 세션에서 Claude에게 이 머신에 설정된 샌드박스 구성을 읽고 이 문서에서 설명하는 경계를 약화시키는 모든 것을 보고하도록 요청하세요. 다음을 가리키세요:

이 단계는 구성 및 상태만 읽습니다. 에이전트를 시작하지 않습니다.

테스트 에이전트를 프로덕션 에이전트를 시작하는 것과 같은 방식으로 시작하고, 손으로 만든 명령으로 시작하지 마세요. 그래야 테스트가 실제 경로를 실행합니다. 아래 격리 확인 섹션에서는 경계의 손 검사를 다룹니다. 에이전트에 단일 작업을 지정하세요: 경계 외부의 모든 것에 도달하려고 시도하고, 무언가가 성공하면 즉시 중지하고 보고하세요. 프롬프트에서 경계를 구체적으로 명명하세요: 호스트, 다른 컨테이너, 컨테이너 런타임 소켓, 클라우드 메타데이터 서비스, 그리고 프록시의 허용 목록에 없는 모든 호스트. 이를 긴밀한 인간 감독 하에서만 실행하고, 모델 API 이상의 인터넷 접근이 없는 호스트에서 실행하며, 성공적인 탈출이 손상을 입히지 않도록 재구축할 준비가 되어 있어야 합니다. 베어 메탈에서는 일회용 VM 내에서 테스트를 실행하세요. 클라우드 VM에서는 새 인스턴스를 사용하고 나중에 삭제하세요. 실행 중인 세션을 지켜보세요. 모든 성공을 차단 요소로 취급하세요: 호스트를 수정하고, 테스트를 반복하며, 테스트가 통과할 때까지 해당 호스트에서 참여를 실행하지 마세요.

에이전트가 시도한 것과 탈출했는지 여부를 확인하세요. 프록시를 통과하지 않은 직접 연결, 자격 증명 파일 또는 메타데이터 주소 읽기, 컨테이너 런타임 소켓 사용 또는 인접한 컨테이너 탐사, 컨테이너 자체 파일 시스템 외부에 쓰기, 에이전트 자체 설정 또는 도구 변경 시도를 찾으세요. 테스트는 각각이 시도되었고 예상한 이유로 실패했음을 기록이 보여줄 때 통과합니다. 각각에 대해 샌드박스 또는 권한 분류자가 이를 중지했는지 기록하세요. 분류자가 거부한 시도는 샌드박스에 도달하지 않았으므로 손 검사로 다루세요(아래 격리 확인 참조). 통과하는 테스트는 최소 기준이지 격리 증명이 아닙니다.

시작 전에 작업을 주어진 대로 완료할 수 있는지 확인하세요. 완료할 수 없는 작업의 예: 찾을 것이 없는 초점 영역, 도달할 수 없는 대상, 없는 버그, 또는 작업에 필요하지만 설치되지 않은 도구. 설정을 변경하거나 새로운 종류의 작업을 시작할 때마다 대상이 빌드되고 도달할 수 있으며 에이전트가 필요한 도구를 가지고 있는지 시작 전에 확인하세요. 같은 이유로 배치를 검토할 때 성공한 것보다 실패했거나 아무것도 찾지 못한 실행의 기록을 먼저 읽으세요.

각 호스트에서 이 검사를 손으로 실행하세요. 두 번째 열은 참조 설계(Kata 런타임 및 Firecracker가 있는 Docker)에 대한 검사를 설명합니다. 자신의 런타임에 맞게 조정하세요.

이 섹션은 참조 구현이 위의 지침을 어떻게 충족하는지 설명합니다. 구현은 포함되지 않습니다. 복사할 수 있는 설계로 읽으세요.

모든 에이전트는 claude -p 자체 microVM 내에서 대상 바이너리 및 소스 옆에서 실행됩니다. microVM은 Kata Containers 컨테이너로, Firecracker 가상 머신 모니터로 지원되며 Docker에 런타임으로 등록됩니다. 에이전트의 Read, Write, 및 Bash 도구는 해당 게스트의 파일 시스템 및 커널만 봅니다.

게스트와 호스트 간의 연결은 의도적으로 작습니다. KVM과 Firecracker가 에뮬레이트하는 몇 가지 가상 장치로 구성됩니다: 컨테이너의 디스크용 블록 장치, 하나의 네트워크 인터페이스, 그리고 Kata가 게스트 내에서 프로세스를 시작하는 데 사용하는 vsock 제어 채널. Firecracker 프로세스 자체는 호스트에서 격리됩니다. 그것은 "감옥"에서 실행되며, 이는 해당 VM의 파일만 보유하는 chroot 디렉토리이고, 자체 마운트 네임스페이스, 컨테이너의 네트워크 네임스페이스, 그리고 Firecracker의 내장 seccomp 필터를 가집니다. 컨테이너의 cgroup에 계산됩니다. 호스트 측에서 신뢰하는 것은 KVM, Firecracker, 그리고 Kata의 런타임 프로세스(Docker가 대화하는 컨테이너별 "shim"로, root로 실행됨)입니다.

오케스트레이터는 신뢰할 수 있는 호스트에 남아 있습니다. 컨테이너 수명 주기를 관리하고, 기록을 스트리밍하며, docker exec로 파일을 이동하고, Kata가 게스트 내의 에이전트를 통해 제공합니다. 런처는 에이전트를 이 샌드박스 내에서만 시작합니다. 에이전트가 시작되기 전에 샌드박스 런타임이 등록되었는지, /dev/kvm이 있는지, 그리고 이그레스 프록시가 작동 중인지 확인하고, 그렇지 않으면 실행을 거부합니다.

샌드박스가 각 표면에 대해 변경하는 것:

각 속성이 적용되는 위치: 하드웨어 가상화는 커널 및 파일 시스템 경계를 제공합니다. 에이전트의 Read/Write/Bash는 게스트 커널에 대해 실행되며, 그 뒤의 Firecracker 프로세스는 호스트에서 격리되고 seccomp로 제한됩니다. 송신 정책은 VM의 네트워크 인터페이스의 호스트 측에서 Docker --internal 브리지(기본 경로 없음)와 해당 네트워크의 두 프록시에 의해 적용됩니다. 자격증명 프록시는 모델 호출만 전달합니다. 송신 프록시는 다른 모든 대상을 거부합니다. 왜냐하면 허용 목록이 비어 있기 때문입니다(추가하지 않는 한). 트래픽은 게스트의 자체 네트워크 스택을 통해 나가며, 필터링은 두 프록시에서 발생합니다.

모델 API의 자격증명(API 키, OAuth 토큰, AWS 또는 Google 자격증명)은 에이전트 컨테이너에 배치되지 않습니다. 호스트의 오케스트레이터가 이를 읽고 검증하며, 각 시작은 하나의 작은 추가 컨테이너인 자격증명 프록시를 시작하여 이를 보유합니다. 프록시는 에이전트의 내부 네트워크에 연결되며, 에이전트 컨테이너는 모델 호출을 이에 보냅니다: 해당 claude CLI는 프록시의 주소를 API 기본 URL로 받으며, 키 또는 토큰이 일반적으로 있을 위치에 고정된 자리 표시자 값을 받습니다. 이는 프록시를 통해서만 모델 API에 도달하고 샌드박스 외부에서 API 키를 주입하는 모범 사례를 따릅니다. 참조 설계에서 프록시는 에이전트의 자체 localhost의 프로세스가 아니라 에이전트 네트워크의 별도 컨테이너입니다. 모든 요청에 대해 프록시는:

손상된 에이전트 컨테이너의 경우, 읽거나 복사하거나 어디든 보낼 수 있는 키, 토큰 또는 자격증명 파일이 없습니다. 클라우드 메타데이터 서비스도 컨테이너에서 도달할 수 없습니다. 컨테이너가 여전히 할 수 있는 것은 실행이 진행되는 동안 프록시를 통해 계정에서 모델 호출을 수행하는 것입니다. 이러한 이유로 에이전트 실행을 위해 좁은 범위의 자격증명을 선호하고, 트랜스크립트에 예상치 못한 동작이 표시되는 모든 실행 후 이를 회전합니다. 프록시는 요청당 한 줄을 기록하며, 클라이언트 주소, 메서드, 경로, 상태 및 크기를 포함합니다. 헤더나 본문을 기록하지 않습니다. 실행이 끝날 때 해당 로그를 저장합니다 (에이전트 트랜스크립트의 오프라인 모니터링의 보존 섹션 참조).

에이전트가 모델 API로 보내는 모든 것은 네트워크를 떠나며, 프록시가 검사하거나 기록하지 않는 요청 본문에 있습니다.

인증 경로별로 각 측이 보유하는 것:

자격증명 프록시 컨테이너는 설정의 신뢰할 수 있는 측의 일부입니다. 샌드박스 런타임이 아닌 일반 runc에서 실행되며, 마운트된 파일을 읽기 위해 필요한 기능을 제외한 모든 기능이 삭제된 루트로 실행되며, 읽기 전용 파일 시스템을 사용합니다. 에이전트의 내부 네트워크에서 자신의 주소에서만 수신하며, 송신 프록시를 통하지 않고 공급자에게 직접 연결합니다. 오케스트레이터는 docker exec를 통해 실행 중인 프록시에 자격증명을 전달합니다. WIF 토큰 파일 및 프로필 경로의 경우, 토큰 또는 프로필을 보유하는 디렉터리가 프록시에 읽기 전용으로 마운트되며, 프록시가 거기서 파일을 읽습니다. 자격증명은 프록시 컨테이너의 환경이나 명령줄에 없으므로 docker inspect가 비밀이 아닌 마운트를 표시합니다.

시작당 하나의 프록시를 시작하고, 실행이 끝나거나 중단될 때 제거합니다. 종료된 실행으로 인해 남겨진 프록시를 확인하고 다음 시작 전에 제거합니다.

자격증명 프록시에는 두 가지 부작용이 있습니다. 첫째, 에이전트의 CLI에 기본이 아닌 API 주소가 제공되므로 기본 주소에만 적용되는 몇 가지 CLI 기능이 에이전트 컨테이너 내에서 꺼집니다. 텔레메트리 및 업데이트 확인도 꺼집니다. 왜냐하면 어차피 나갈 경로가 없기 때문입니다. 둘째, Vertex에서 프록시의 경로 필터는 에이전트 컨테이너가 나머지 Vertex AI API를 사용하지 못하도록 하는 주요 제어입니다 (송신 허용 목록 참조). 시작 시 키의 IAM 범위 확인이 두 번째 계층입니다.

송신 프록시의 허용 목록은 기본적으로 비어 있습니다. 에이전트 컨테이너는 자격증명 프록시를 통해서만 모델 API에 도달합니다 (자격증명 프록시 참조). 각 시작은 자격증명이 선택하는 공급자에 대해 해당 프록시를 시작하므로 샌드박스 설정에 공급자별 항목이 저장되지 않습니다. 에이전트가 송신 프록시를 통해 요청하는 다른 모든 대상(모델 API 호스트 자체 포함)은 403 및 로그의 거부 라인을 받습니다. Bedrock 및 Vertex 엔드포인트를 선택하는 지역 값(AWS_REGION, CLOUD_ML_REGION)은 사용되기 전에 엄격한 패턴에 대해 확인되므로 잘못된 값이 자격증명을 다른 호스트로 보낼 수 없습니다.

Vertex에는 주의해야 할 한 가지 제한이 있습니다. …aiplatform.googleapis.com은 전체 Vertex AI API를 제공하므로 사용자 정의 작업을 만들 수 있는 자격증명은 프로젝트에서 전체 인터넷 송신이 있는 임의의 컨테이너를 실행할 수 있습니다. 이에 대해 두 가지 제어를 사용합니다. 자격증명 프록시가 구성된 프로젝트에서만 게시자 모델 호출을 전달하도록 합니다(…/publishers/anthropic/models/…:rawPredict, :streamRawPredict 및 :countTokens) 및 다른 모든 경로를 거부합니다. 그리고 시작 시 키의 IAM 범위를 확인하고 폐쇄적으로 실패합니다: gcloud 사용자 ADC를 거부하고, testIamPermissions을 사용하여 서비스 계정 키를 확인하고, 워크로드 생성 권한이 있으면 거부합니다. 계정에 aiplatform.endpoints.predict만 보유하는 사용자 정의 역할을 부여합니다. 메타데이터 서버, Google의 STS 및 IAM 자격증명 엔드포인트는 에이전트 컨테이너에서 도달할 수 없어야 합니다.

에이전트가 패키지 미러 또는 범위 내 대상과 같은 추가 호스트에 도달해야 하는 경우, 송신 프록시의 허용 목록에 host:port 항목으로 추가합니다. 참여에 필요한 것만 추가합니다 (범위 및 감독 참조).

이 목록에 model-API 호스트를 추가하지 마세요. 에이전트는 이를 필요로 하지 않습니다. 에이전트의 모델 호출이 자격증명 프록시를 통해 이루어지기 때문입니다. 이를 추가하면 에이전트 컨테이너에 API로의 직접 경로가 생기며, 권한 분류기에 전달되는 정보를 포함한 나머지 설계는 이들이 그러한 경로를 갖지 않는다고 가정합니다.

허용 목록을 변경하면 이그레스 프록시를 다시 시작해야 하며, 이는 활성 에이전트 연결을 끊습니다. 배치 중간이 아닌 배치 사이에 수행하고, 그 후 프록시가 로드한 목록을 확인하세요.

자격증명 구성에서 공급자 엔드포인트를 파생시키고, 호스트에 설정된 ANTHROPIC_BASE_URL과 같은 기본 URL 변수는 무시하세요. 자격증명 프록시는 항상 자격증명이 선택한 엔드포인트로 전달해야 합니다.

이 섹션은 참조 구현에서 Kata와 Firecracker를 사용하여 에이전트를 실행하면서 배운 내용을 수집합니다. 이는 설치 단계 집합이 아닙니다.

참조 설계에는 물리적 Linux 머신 또는 자체적으로 VM을 실행할 수 있는 VM이 필요합니다:

해당 샌드박스에는 Linux 호스트의 KVM이 필요합니다. Mac의 Docker는 사용자의 홈 디렉토리를 마운트하고 Docker 데몬을 보유하는 공유 Linux VM 내부에서 실행되므로 에이전트별 하드웨어 격리를 제공할 수 없습니다. Mac에서 작업하는 경우 KVM이 있는 Linux 호스트(베어 메탈 또는 중첩 가상화가 있는 클라우드 VM)에서 에이전트를 실행하고 SSH를 통해 구동하세요. macOS 또는 Windows에서 자신의 샌드박스를 구축하는 경우 위의 일반 지침 섹션에 명시된 하이퍼바이저를 참조하세요.

devmapper 스냅샷터로 전환한 후 Docker의 이전 저장소에서 생성된 이미지 및 컨테이너는 Docker에 보이지 않습니다. 이들은 디스크에 남아 있습니다. 다시 보려면 daemon.json(storage-driver 및 features.containerd-snapshotter)에 두 저장소 설정을 이전 상태로 되돌리고 Docker를 다시 시작하세요.

Kata 릴리스를 고정하고 설치하기 전에 해당 다이제스트를 확인하세요. 참조 설계는 Kata의 Firecracker 프로필에서 시작하여 /etc/kata-containers/configuration.toml에서 이러한 설정을 고정합니다:

Kata 릴리스와 함께 제공되는 kernel, image, kernel_params 값은 그대로 유지됩니다.

모든 VM은 동일한 두 파일에서 부팅되며, Kata는 이를 모든 jail에 바인드 마운트하고, jailer는 root로 시작되므로 일반 파일 권한으로는 손상된 Firecracker 프로세스가 이후 모든 VM이 부팅하는 이미지를 다시 쓰는 것을 막을 수 없습니다. 둘 다에 불변 플래그를 설정하세요(chattr +i). 해당 플래그를 지우려면 Firecracker의 seccomp 필터가 허용하지 않는 시스템 호출이 필요하며, 이는 jail 내부의 root도 이를 수행하지 못하도록 설계되었습니다. 새 Kata 릴리스를 설치하기 전에 플래그를 직접 지우세요. chattr 지원이 없는 파일 시스템에서는 대신 읽기 전용 바인드 마운트를 사용하세요.

각 에이전트 VM은 부팅 시 한 번 크기가 조정됩니다: default_memory 더하기 컨테이너의 --memory. 4096 MiB 기본값과 4g 컨테이너 제한이 있으면 에이전트는 8 GiB VM입니다. 호스트는 게스트가 사용할 때 VM에 메모리를 할당하며, 부팅 시 모두 할당하지는 않지만 동시 에이전트당 전체 양을 계획하세요: 병렬로 10개 에이전트는 80 GiB로 증가할 수 있습니다. 컨테이너의 --memory 제한이 전체 VM을 제한하는지 여부는 호스트의 cgroup 레이아웃에 따라 다릅니다. 호스트에서 어느 것이 적용되는지 확인하세요:

모든 종류의 호스트에서 이 동작을 확인하지 않았습니다. 어느 쪽이든 호스트를 VM 크기로 크기 조정하세요.

각 VM은 default_vcpus를 가져옵니다. Firecracker는 실행 중인 VM에 CPU를 추가할 수 없으므로 빌드 집약적 대상의 경우 시작 전에 값을 높이세요. 최대값은 VM당 32입니다.

모든 이미지와 모든 컨테이너는 이미지 저장소를 지원하는 device-mapper thin pool에서 가상 디스크를 가져옵니다. 풀이 가득 차면 컨테이너 내 쓰기가 I/O 또는 공간 부족 오류로 실패합니다. 풀을 보유한 파일 시스템이 먼저 가득 차면 풀이 읽기 전용이 되고 그 위의 모든 컨테이너가 실패합니다. docker rmi 및 docker system prune으로 여유 공간을 확보하세요(해제된 블록이 풀로 반환됨). sudo dmsetup status <pool>는 사용량을 표시합니다. 오래 실행되는 호스트의 경우 전용 디스크의 LVM thin pool이 더 나은 레이아웃입니다.

모든 에이전트 시작은 게스트 커널을 부팅합니다. 이는 베어 메탈에서 1초 미만, 중첩 가상화에서 몇 초 정도 걸리며, 이는 에이전트 실행 시간에 비해 작습니다.

새 머신을 설정한 후 이 시퀀스는 샌드박스가 종단 간 작동함을 보여줍니다. 3단계와 4단계는 실제 모델 호출을 수행합니다.

Kata와 Firecracker에서 에이전트를 실행하는 것은 일반 컨테이너를 실행하는 것과 다음과 같은 방식으로 다릅니다.

Firecracker는 호스트 파일 시스템 공유가 없으므로 Kata는 컨테이너 시작 시 바인드 마운트된 파일 또는 디렉토리를 게스트에 복사하고, 나중에 호스트의 변경 사항은 내부에서 보이지 않습니다. 이는 대상 소스와 같이 실행 중에 변경되지 않는 입력에는 문제가 없으며, 이들은 읽기 전용 마운트로 유지될 수 있습니다. 에이전트 컨테이너가 보유하지 않으므로 자격증 파일은 마운트되거나 스트리밍되지 않습니다(자격증 프록시 참조). 실행 중에 변경되는 파일은 오케스트레이터가 docker exec를 통해 컨테이너에 기록하고 최신 상태로 유지해야 합니다. 컨테이너 내 복사본은 에이전트가 편집할 수 있는 일반 파일이므로 오케스트레이터가 호스트의 원본을 읽고 테스트 중인 에이전트가 도달할 수 없는 복사본에서 결과를 판단하도록 하세요.

마이크로VM의 네트워크 인터페이스는 VM이 부팅할 때 존재해야 합니다. Firecracker는 나중에 인터페이스를 추가할 수 없습니다. 그러나 Docker는 런타임이 컨테이너를 생성한 후에만 컨테이너의 네트워크를 연결합니다. 참조 설계는 이를 해결합니다. 먼저 올바른 네트워크에 연결되고 sleep만 실행하는 작은 유휴 컨테이너를 시작한 다음 해당 컨테이너의 네트워크 네임스페이스 내에서 에이전트를 시작합니다(--network container:<name>). Kata는 부팅 시 인터페이스를 찾아 VM에 연결합니다. 동반은 정확히 하나의 VM을 제공합니다. Kata는 VM의 호스트 측 네트워크 디바이스를 그 안에 남겨두므로 쌍을 함께 생성 및 제거하고 동반을 재사용하지 마세요. 하나는 대략 12 MB의 유휴 프로세스 비용이 듭니다.

docker rm -f <agent-container>로 충분합니다. 오케스트레이터는 죽은 컨테이너를 감지하고 실행을 실패로 표시한 다음 실행을 해제할 때 동반 컨테이너를 제거해야 합니다.

Docker의 내장 DNS는 호스트 측 네트워크 네임스페이스에서 실행되며 게스트 내부에서 도달할 수 없으므로, 프록시를 IP 주소로 에이전트에 전달하고 네트워크 대상에 정적 IP를 지정하세요.

docker exec를 에이전트 컨테이너에 실행하면 정상적으로 작동합니다. Kata의 게스트 내부 에이전트가 명령을 실행합니다. docker cp를 에이전트 컨테이너로 또는 컨테이너에서 복사하면 작동하지 않습니다. 컨테이너의 파일이 게스트 내부의 가상 디스크에 있기 때문입니다. docker exec <container> cat <path> 등을 사용하세요.

Kata는 jailer를 uid 0으로 시작하므로 Firecracker 프로세스는 권한이 없는 사용자 ID가 아닌 chroot, 네임스페이스, seccomp 필터 및 cgroup으로 제한됩니다. 모든 VM이 공유하는 두 파일인 게스트 커널과 이미지는 대신 불변 플래그로 보호됩니다(Kata 설정 참조).

Kata는 Firecracker를 이전 Go 런타임을 통해 실행합니다. Kata 4.0은 다른 하이퍼바이저에 대해 더 새로운 Rust 런타임을 기본값으로 설정했으며 Go 런타임을 더 이상 사용하지 않습니다. 업스트림에 따르면 Go 런타임은 여전히 중요한 버그 수정 및 CVE 수정을 받으며 Kata 5.0 이전에는 제거되지 않을 수 있습니다. Rust 런타임은 하이퍼바이저 중 Firecracker를 나열하지 않으며 업스트림은 주로 QEMU를 사용하여 Docker 통합을 테스트합니다. 마이그레이션을 계획하세요. Kata 버전을 변경할 때 새 호스트 검증을 반복하세요. Kata는 Firecracker 대신 Cloud Hypervisor를 사용할 수도 있습니다. 참조 구현은 해당 구성을 테스트하거나 강화하지 않았습니다.

Kata의 런타임, Firecracker 및 게스트 에이전트 메시지는 저널로 이동합니다: journalctl -t kata. containerd 및 Docker 문제는 journalctl -u containerd 및 journalctl -u docker에 있습니다.