아키텍처

아키텍처 (Architecture)

Docker Sandboxes가 내부적으로 어떻게 동작하는지, 그 구조를 설명해 드릴게요.

출처: 문서

본문

이 페이지는 로컬 샌드박스를 설명해요. 클라우드 동작과 제한 사항은 로컬과 클라우드 샌드박스 비교 문서를 보세요.

이 페이지는 Docker Sandboxes가 내부에서 어떻게 동작하는지 설명해요. 아키텍처의 보안 속성은 Sandbox isolation 문서를 보세요.

워크스페이스 저장소 (Workspace storage)

sbx 버전 0.42.0부터 sbx create에서 워크스페이스 경로는 선택 사항이에요. 생략하면 샌드박스에 호스트 워크스페이스 바인드 마운트가 없어요. 샌드박스는 템플릿 이미지에 설정된 WORKDIR을 기본 작업 디렉터리로 사용해요. Docker가 제공하는 에이전트 템플릿은 WORKDIR을 /home/agent/workspace로 설정해요. 커스텀 템플릿은 다른 절대 경로를 설정할 수 있어요. 데몬이 이미지 설정에서 쓸 수 있는 절대 WORKDIR을 해석하지 못하면 /home/agent/workspace로 대체해요. 거기서 만든 파일은 샌드박스 안에 남고, 멈추고 재시작해도 유지돼요.

sbx create나 sbx run에 워크스페이스 경로를 전달하면 그 디렉터리가 파일시스템 패스스루(filesystem passthrough)를 통해 샌드박스에 마운트돼요. sbx run은 경로를 전달하지 않으면 현재 디렉터리를 사용해요. 샌드박스는 실제 호스트 파일을 보게 되므로, 어느 방향으로든 변경이 동기화 과정 없이 즉시 반영돼요.

직접 마운트된 워크스페이스는 호스트와 같은 절대 경로에 나타나요. 절대 경로를 유지하면 오류 메시지, 설정 파일, 빌드 산출물이 모두 호스트에서 찾을 수 있는 경로를 가리켜요. 에이전트도 같은 디렉터리 구조를 보므로, 디버깅이나 변경 검토 때 혼란이 줄어요.

Clone mode는 세 번째 저장소 레이아웃을 사용해요. 호스트 저장소가 /run/sandbox/source에 읽기 전용으로 마운트되고, 에이전트는 샌드박스 안의 개인 클론에서 작업해요. Clone mode 문서를 보세요.

경고 (Warning): 네트워크 연결 또는 원격 저장소(네트워크 드라이브, SMB/NFS 공유, 클라우드 동기화 폴더)를 워크스페이스로 마운트하지 마세요. 샌드박스는 파일시스템 패스스루로 워크스페이스에 접근하므로 모든 파일 읽기·쓰기가 네트워크를 거쳐요. 이로 인해 지연이 늘고 에이전트 성능이 느려져요.

저장소와 지속성 (Storage and persistence)

샌드박스를 만들면 안의 모든 것이 제거하기 전까지 유지돼요: 에이전트가 빌드하거나 pull 한 Docker 이미지와 컨테이너, 설치된 패키지, 에이전트 상태와 기록, 마운트 없는 워크스페이스나 클론 워크스페이스의 파일이에요. 직접 마운트된 워크스페이스의 파일은 대신 호스트에 살아 있어요.

각 샌드박스는 자체 Docker 데몬 상태, 이미지 캐시, 패키지 설치는 유지해요. 여러 샌드박스는 이미지나 레이어를 공유하지 않아요. 공유 에이전트 스킬 스토어(shared agent skills store)는 예외예요: 지원되는 에이전트용 샌드박스는 같은 호스트 쪽 스토어를 기본적으로 읽기 전용으로 마운트해요. --skills 또는 skills.defaultMode를 사용해 생성 시 다른 모드를 고를 수 있어요. 기존 샌드박스는 다시 만들기 전까지 마운트를 유지해요.

각 샌드박스는 VM 이미지, Docker 이미지, 컨테이너 레이어, 볼륨으로 디스크 공간을 소비하며, 이미지를 빌드하고 패키지를 설치할수록 커져요.

직접 마운트된 워크스페이스에는 모든 OS에서 기본적으로 virtiofs 캐싱이 켜져 있어요. 샌드박스 VM의 파일 읽기가 호스트 쪽에서 캐시되어 파일시스템 패스스루 왕복을 줄이고, git status나 디렉터리 스캔 같은 읽기 중심 워크로드의 성능을 높여요. 끄려면 샌드박스를 만들 때 DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0을 설정하세요:

$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent>

네트워킹 (Networking)

샌드박스의 모든 아웃바운드 TCP 트래픽은 호스트의 프록시를 통해 라우팅돼요. 에이전트는 HTTP와 HTTPS에 포워드 프록시를 사용하고, 다른 TCP 트래픽은 투명하게 전달돼요. 두 경로 모두 네트워크 접근 정책을 적용해요. 포워드 프록시는 자격 증명 주입(credential injection)도 처리해요. 동작 방식은 Network isolation 문서, 기본 허용 범위는 Default security posture 문서를 보세요.

인증된 요청 따라가기 (Follow an authenticated request)

아래 다이어그램을 따라가며 Docker Sandboxes가 네트워크 정책을 확인하고 센티널(sentinel) 자격 증명을 실제 값으로 바꾸는 위치를 확인해요. 실제 자격 증명은 요청 내내 샌드박스 밖에 유지돼요.

다음(Next)과 이전(Previous)으로 여러분의 속도에 맞춰 요청을 따라가거나, 단계를 선택해 이동할 수 있어요.

• 에이전트가 요청을 준비해요: 에이전트는 실제 API 자격 증명 대신 센티널 값을 봐요.
• 요청이 microVM을 떠나요: 아웃바운드 HTTP·HTTPS 트래픽이 호스트 네트워크 경로를 통해 샌드박스 경계를 건너요.
• 네트워크 정책이 목적지를 확인해요: 활성 정책이 제공 업체 도메인을 허용할 때만 요청이 계속돼요.
• 프록시가 자격 증명을 가져와요: 호스트 쪽 프록시가 일치하는 자격 증명을 샌드박스로 복사하지 않고 해석해요.
• 프록시가 헤더를 다시 써요: 프록시가 요청이 microVM을 떠난 뒤 센티널을 실제 자격 증명으로 바꿔요.
• 응답이 돌아와요: 제공 업체 응답이 호스트 프록시를 통해 에이전트로 돌아와요. 자격 증명은 호스트에 남아 있어요.

업스트림 프록시 (Upstream proxy)

호스트 쪽 프록시는 여러분의 호스트 네트워크 구성과 라우팅을 사용해 아웃바운드 연결을 만들어요. 목적지가 직접 경로로 도달 가능하면 그 경로를 따라요. 목적지에 도달하려면 업스트림 프록시가 필요하면, 호스트 쪽 프록시가 그 프록시로 요청을 전달해요. 업스트림 프록시로 연결을 이어가면 샌드박스 트래픽이 호스트의 다른 애플리케이션과 같은 이그레스(egress) 제어를 따르게 돼요.

기본적으로 샌드박스 트래픽과 데몬의 자체 트래픽 모두 OS 시스템 프록시를 따르므로, 보통 별도 설정 없이 동작해요. 프록시 URL, PAC 파일, SOCKS5 프록시, 또는 샌드박스·데몬 트래픽을 분리한 설정으로 프록시를 명시적으로 지정하려면 Configure an upstream proxy 문서를 보세요. 업스트림 프록시 지원은 실험적이며 바뀔 수 있어요.

HTTP와 HTTPS 트래픽만 업스트림 프록시로 전달할 수 있어요. 다른 TCP 트래픽은 프록시로 리다이렉트할 수 없어요.

MCP 게이트웨이 (MCP gateway)

지원되는 에이전트는 샌드박스용 단일 MCP 게이트웨이 엔드포인트에 연결해요. 게이트웨이는 샌드박스 경계의 호스트 쪽에서 실행되며 등록된 MCP 서버에 대한 접근을 중개(broker)해요.

등록된 MCP 서버는 원격 엔드포인트이거나 호스트에서 실행되는 로컬 stdio 서버일 수 있어요. 로컬 stdio 서버는 샌드박스 VM 안에서 실행되지 않아요. 로컬 stdio 서버가 OCI 이미지로 패키징되어 있거나 명시적 docker 명령을 등록했다면, 호스트의 Docker를 사용해요.

MCP 정책이 적용되면 시행은 HTTP/HTTPS 네트워크 프록시와 분리된 MCP 게이트웨이 경로에서 이뤄져요. 서버 등록은 저장되기 전에 확인되고, 관리 대상 MCP 요청은 도구 호출, 리소스 읽기, 프롬프트 검색, 게이트웨이 메타-도구 실행 전에 게이트웨이가 확인해요.

수명 주기 (Lifecycle)

sbx run은 지정된 에이전트용 VM을 초기화하고 에이전트를 시작해요. VM을 다시 만들지 않고 멈추고 재시작할 수 있으며, 설치된 패키지, Docker 이미지, 샌드박스 안 파일이 유지돼요.

샌드박스는 명시적으로 제거하기 전까지 유지돼요. 에이전트를 멈추는 것은 VM을 삭제하지 않아요. 환경 설정이 실행 사이에 이어져요. sbx rm으로 샌드박스, 그 VM, 모든 내용물을 삭제해요. 샌드박스가 --clone을 사용했다면 sandbox-<name> Git 원격도 호스트 저장소에서 제거돼요.

다른 방법과 비교 (Comparison to alternatives)

샌드박스는 더 높은 리소스 오버헤드(VM + 자체 데몬)와 완전한 격리를 맞바꿔요. Docker 접근 없이 가벼운 패키징이 필요하면 컨테이너를 사용하세요. 호스트 환경을 신뢰하지 않으면서 자율적인 것에 완전한 Docker 기능을 주고 싶을 때 샌드박스를 사용하세요.

더 알아보기 (Learn more)

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