격리 계층

격리 계층 (Isolation layers)

Docker Sandboxes가 호스트를 보호하는 다섯 가지 격리 계층을 알아볼게요.

출처: 문서

본문

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

AI 코딩 에이전트는 여러분을 대신해 코드를 실행하고, 패키지를 설치하고, 도구를 실행해야 해요. Docker Sandboxes는 각 에이전트를 자체 마이크로VM에서 실행해요. 하이퍼바이저, 네트워크, Docker Engine, 워크스페이스, 자격 증명 프록시라는 다섯 격리 계층이 호스트를 보호해요.

하이퍼바이저 격리 (Hypervisor isolation)

모든 샌드박스는 자체 Linux 커널을 가진 경량 마이크로VM 안에서 실행돼요. 호스트 커널을 공유하는 컨테이너와 달리, 샌드박스 VM은 정의된 경계 밖의 호스트 프로세스, 파일, 리소스에 접근할 수 없어요.

  • 프로세스 격리: 샌드박스마다 별도 커널. VM 안의 프로세스는 여러분의 호스트와 다른 샌드박스에서 보이지 않아요.
  • 파일시스템 격리: 워크스페이스 경로를 전달하거나 기본적으로 현재 디렉터리를 사용하는 sbx run을 사용할 때 호스트 워크스페이스가 공유돼요. 옵트아웃하지 않은 지원 에이전트의 경우 전용 공유 스킬 저장소도 호스트와 공유돼요. VM 파일시스템의 나머지는 재시작에도 유지되지만 샌드박스를 삭제하면 제거돼요. 워크스페이스 범위 밖을 가리키는 심볼릭 링크는 따르지 않아요.
  • 전체 정리: sbx rm으로 샌드박스를 제거하면 VM과 그 안의 모든 것이 삭제돼요.

에이전트는 VM 안에서 sudo 권한을 가진 비-root 사용자로 실행돼요. 하이퍼바이저 경계가 격리 제어이며, VM 안 권한 분리가 아니에요.

로컬 샌드박스의 프로세스는 텍스트를 호스트 클립보드에 쓸 수 있지만, 기존 클립보드 텍스트는 읽을 수 없어요. 호스트 클립보드 이미지 읽기는 별도의 옵트인 기능이에요. 신뢰하지 않는 코드를 실행한 후에는 호스트에 붙여넣기 전에 클립보드 내용을 확인하세요.

네트워크 격리 (Network isolation)

각 샌드박스는 자체 격리된 네트워크를 가져요. 샌드박스는 서로 직접 통신할 수 없고 여러분의 호스트와 네트워크를 공유하지 않아요. 정책 제어 연결을 통해 호스트에서 실행 중인 서비스에 도달하려면 샌드박스에서 호스트 서비스에 접근하기를 참고하세요.

모든 아웃바운드 TCP 트래픽은 네트워크 접근 정책을 시행하는 호스트의 프록시를 통과해요. 샌드박스는 클라이언트 구성에 따라 포워드 프록시 또는 투명 프록시로 트래픽을 라우팅해요. 둘 다 네트워크 정책을 시행해요. AI 서비스용 자격 증명을 주입하는 것은 포워드 프록시뿐이에요.

아웃바운드 UDP는 기본적으로 비활성화돼요. 실험적 UDP 이그레스를 켜면 네트워크 정책이 그 대상을 제어해요. ICMP는 차단돼요. DNS 쿼리는 네트워크 정책을 시행하는 샌드박스의 내부 해석기를 사용해요. TCP 연결은 정책 규칙이 대상을 매칭할 때만 허용돼요.

기본 허용 도메인 집합은 기본 보안 자세를 참고하세요. 허용된 트래픽을 회사 또는 상위 프록시로 전달하려면 상위 프록시 구성을 참고하세요.

Docker Engine 격리 (Docker Engine isolation)

에이전트는 종종 이미지를 빌드하고, 컨테이너를 실행하고, Docker Compose를 사용해야 해요. 호스트 Docker 소켓을 컨테이너에 마운트하면 에이전트가 여러분의 환경에 완전히 접근하게 돼요.

Docker Sandboxes는 샌드박스 환경 안에서 호스트와 격리된 별도의 Docker Engine을 실행해 이를 피해요. 에이전트가 docker build나 docker compose up을 실행하면 그 명령이 그 엔진에 대해 실행돼요. 에이전트는 호스트 Docker 데몬으로의 경로가 없어요.

이 Docker Engine 경계는 샌드박스 VM 안에서 실행되는 프로세스에 적용돼요. MCP 게이트웨이를 통해 등록된 로컬 stdio MCP 서버에는 적용되지 않아요. 그 서버들은 샌드박스 VM 밖인 호스트에서 실행돼요. 로컬 MCP 서버가 Docker 컨테이너를 시작하면 호스트의 Docker를 사용해요.

각 샌드박스 VM은 자체 Docker Engine을 실행해요. 에이전트는 VM 안에서 그 엔진과 함께 실행되며, 모두 VM 안에서 컨테이너를 만들도록 이를 구동해요:

flowchart TB
  subgraph host["Host system"]
    subgraph hostd["Host Docker daemon"]
      hc["Your containers and images"]
    end
    subgraph vm["Sandbox (microVM)"]
      a["Agent"]
      subgraph e["Sandbox Docker engine"]
        c["Containers created by agent"]
      end
      a -->|"docker build / compose up"| e
    end
  end
  style host fill:#3b82f622,stroke:#3b82f6

워크스페이스 격리 (Workspace isolation)

샌드박스를 만들 때 에이전트가 워크스페이스를 받는 방식을 선택하세요:

  • 마운트 없음(Mountless) (sbx create에 경로 없음): 샌드박스가 호스트 워크스페이스를 받지 않아요. 에이전트는 샌드박스 자체 파일시스템에서 작업해요.
  • 직접 마운트(Direct mount) (. 같은 경로): 에이전트가 여러분의 작업 트리에 읽기-쓰기로 접근해요. 에이전트의 편집과 여러분의 호스트 파일시스템 사이에 경계가 없어요.
  • 클론 모드(Clone mode) (--clone과 Git 경로): 저장소가 VM에 읽기 전용으로 마운트되고 에이전트는 VM 안의 개인 클론에서 작업해요. 여러분이 가져올(fetch) 때까지 에이전트의 편집은 호스트에 절대 도달하지 않아요.

직접 마운트와 클론 모드 워크플로우는 Git 워크플로우를 참고하세요.

마운트 없음 (Mountless)

마운트 없는 샌드박스를 만들려면 sbx create에서 워크스페이스 경로를 생략하고 이름으로 붙으세요:

$ sbx create --name scratch claude
$ sbx run --name scratch

에이전트는 샌드박스 템플릿의 기본 작업 디렉터리를 사용해요. Docker가 제공하는 에이전트 템플릿은 /home/agent/workspace를 사용해요. 템플릿이 사용 가능한 절대 작업 디렉터리를 정의하지 않으면 데몬이 그 경로를 사용해요. 그곳의 파일은 샌드박스 안에 남고, 중지·재시작에도 유지되며, 샌드박스를 제거하면 삭제돼요. 마운트 없는 샌드박스는 호스트 프로젝트 디렉터리를 노출하지 않지만, 공유 스킬 저장소 같은 별도로 구성된 호스트 리소스는 여전히 마운트될 수 있어요.

직접 마운트 (Direct mount)

워크스페이스 경로를 전달해 읽기-쓰기 마운트로 VM에 공유하세요. 에이전트와 호스트는 같은 파일을 보고, 에이전트가 만든 변경은 쓰이자마자 여러분의 호스트에 나타나요. sbx run은 경로를 전달하지 않으면 현재 디렉터리를 마운트해요:

$ sbx run claude

직접 마운트는 경로로 접근을 시행해요. 워크스페이스 파일이 워크스페이스 밖 파일의 하드 링크라면, 에이전트는 워크스페이스 경로를 통해 밑바탕 파일을 읽고 수정할 수 있어요. 변경은 승인된 워크스페이스 밖의 링크를 포함해 그 파일의 모든 하드 링크에 영향을 줘요. 파일시스템 접근 정책은 워크스페이스 경로를 평가할 뿐 같은 파일의 다른 경로는 평가하지 않으므로 이 접근을 막지 않아요. 클론 모드는 호스트 저장소를 읽기 전용으로 마운트해 기본 워크스페이스를 통한 쓰기를 막아요.

직접 마운트는 에이전트에게 작업 공간에 대한 넓은 쓰기 접근을 줘요. 에이전트는 다음을 포함한 워크스페이스 파일을 생성, 수정, 삭제할 수 있어요:

  • 소스 코드와 구성 파일
  • 빌드 파일(Makefile, package.json, Cargo.toml)
  • Git 훅(.git/hooks/)
  • CI 구성(.github/workflows/, .gitlab-ci.yml)
  • IDE 구성(.vscode/tasks.json, .idea/ 실행 구성)
  • AI 프로젝트 구성과 설정(.claude/, .codex/, .gemini/)
  • 숨김 파일, 셸 스크립트, 실행 파일

이 파일 중 일부는 커밋, 푸시, 빌드, IDE에서 프로젝트 열기 같은 정상 개발 동작을 촉발할 때 코드를 실행해요. 에이전트 세션 후 그 동작을 수행하기 전에 검토하세요:

  • Git 훅(.git/hooks/)은 커밋, 푸시, 기타 Git 동작에 실행돼요. 이들은 .git/ 안에 있어 git diff 출력에 나타나지 않으므로 ls -la .git/hooks/로 별도 확인하세요.
  • CI 구성(.github/workflows/, .gitlab-ci.yml)은 푸시에 실행돼요.
  • 빌드 파일(Makefile, package.json 스크립트, Cargo.toml)은 빌드나 설치 단계에 실행돼요.
  • IDE 구성(.vscode/tasks.json, .idea/)은 프로젝트를 열 때 작업을 실행할 수 있어요.
  • AI 프로젝트 구성과 설정(.claude/settings.json, .codex/config.toml, .gemini/settings.json)은 자동으로 실행되는 훅과 시작 명령을 정의할 수 있어요.

샌드박스 환경 파일 (Sandbox environment files)

샌드박스 환경 파일은 여러분의 권한으로 호스트에서 실행되는 수명주기와 자격 증명 명령을 선언할 수 있어요. 이 명령을 실행하기 전에 sbx는 환경 계획에 그 명령을 보여주고 승인을 요청해요. 호스트 명령을 승인하기 전에 계획을 검토하세요.

파일 배치와 읽기 전용 보호는 샌드박스 환경 파일을 참고하세요.

[!WARNING] 샌드박스가 수정한 워크스페이스 파일을 신뢰하지 않는 기여자가 보낸 풀 리퀘스트처럼 취급하세요: 호스트에서 신뢰하기 전에 검토하세요.

클론 모드 (Clone mode)

--clone으로 샌드박스를 시작하면 에이전트는 절대 여러분의 호스트 저장소에 직접 작업하지 않아요. VM 안에서 완전한 root가 있어도 .git 디렉터리, 작업 트리, 호스트의 추적된 파일을 수정할 수 없어요.

[!IMPORTANT] 클론 모드는 호스트 저장소를 수정으로부터 보호하지 열람으로부터 보호하지 않아요. 저장소는 여전히 샌드박스에 읽기 전용으로 마운트되며, 추적되지 않은 파일과 .gitignore로 제외된 파일을 포함해요. .env 같은 파일은 에이전트가 계속 읽을 수 있어요. 비밀은 작업 디렉터리 밖에 두거나 자격 증명 격리를 사용하세요.

flowchart LR
  subgraph host["Host repository (untouched)"]
    direction TB
    repo[".git/ + working tree"]
    remote["remote sandbox-<name>"]
  end
  subgraph vm["Sandbox VM"]
    direction TB
    mount["/run/sandbox/source<br/>(read-only bind mount)"]
    clone["private clone (RW)<br/>agent edits here"]
    daemon["git-daemon"]
  end
  repo -->|"read-only bind mount"| mount
  mount -->|"git clone"| clone
  clone --> daemon
  daemon -->|"git fetch"| remote

경계가 시행되는 방식:

  • 저장소의 Git root가 /run/sandbox/source에 읽기 전용으로 마운트돼요. 마운트는 추적되지 않은 파일과 .gitignore로 제외된 파일을 포함한 전체 작업 디렉터리를 다뤄요. 에이전트가 VM 안에서 하는 어떤 것도 그 마운트를 통해 되쓸 수 없지만, Git root 아래의 모든 파일은 샌드박스 안에서 읽을 수 있어요. 여기에는 Git이 추적하지 않는 .env 같은 자격 증명 파일이 포함돼요.
  • 에이전트는 샌드박스 안에 사는 개인 클론에서 작업해요. 클론은 자체 인덱스, 자체 refs, 자체 작업 트리를 가져요. 클론에 대한 쓰기는 호스트에 절대 도달하지 않아요.
  • 샌드박스는 호스트의 localhost에 바인딩된 Git 데몬을 통해 클론을 게시해요. CLI가 호스트 저장소에 sandbox-<sandbox-name> Git remote로 연결해요. 그 remote에서 가져오는 것은 제3자 remote에서 가져오는 것과 같은 신뢰 모델을 사용해요 — 명시적으로 병합하거나 가져온 refs를 체크아웃하기 전에는 아무것도 통합되지 않아요.

실용적 보장:

  • 에이전트는 호스트의 추적된 파일이나 .git/ 아래의 어떤 바이트도 수정할 수 없어요. 손상되거나 버그 있는 에이전트도 .git/hooks/pre-commit을 떨어뜨리거나, .github/workflows/를 바꾸거나, 작업 트리에 변경을 몰래 넣을 수 없어요.
  • 호스트와 샌드박스 안의 동시 git 명령은 공유 .git/index나 공유 refs에서 경쟁할 수 없어요 — 공유되는 쓰기 가능한 Git 상태가 없어요.
  • 저장소 .git/config의 자격 증명, 서명 키, 설정은 호스트에 남아요. 에이전트의 클론은 자체 독립 구성을 가져요.

에이전트의 Git 활동과 호스트 저장소 사이에 강한 경계를 원할 때 클론 모드를 사용하세요 — 예를 들어 익숙하지 않은 에이전트를 실행하거나, 같은 저장소에서 동시에 여러 에이전트를 실행하거나, 에이전트가 작업하는 동안 작업 트리를 깨끗하게 유지하고 싶을 때.

자격 증명 격리 (Credential isolation)

대부분의 에이전트는 모델 제공자용 API 키가 필요해요. 키를 샌드박스에 전달하는 대신, 호스트 측 프록시가 아웃바운드 API 요청을 가로채 각 요청을 전달하기 전에 인증 헤더를 주입해요.

자격 증명 값은 VM 안에 절대 저장되지 않아요. 명시적으로 설정하지 않는 한 샌드박스 안의 환경 변수나 파일로도 사용할 수 없어요. 따라서 손상된 샌드박스도 로컬 환경에서 API 키를 읽을 수 없어요.

SSH 에이전트 포워딩은 기본적으로 활성화돼요. 개인 키는 호스트에 남지만, 샌드박스 안의 어떤 프로세스든 포워딩된 에이전트에 인증이나 데이터 서명을 요청할 수 있어요. Docker Sandboxes는 SSH 에이전트로 인식하는 소켓만 포워딩해요. 포워딩이 비활성화되거나, 구성이 없거나, 선택한 소켓을 사용할 수 없으면 샌드박스는 SSH 에이전트를 받지 못해요.

자격 증명 저장과 관리 방법은 자격 증명을 참고하세요.

더 알아보기 (Learn more)