에이전트에게 열쇠 대신 출입증을: NVIDIA OpenShell의 게이트웨이·슈퍼바이저·샌드박스 분리, 자격 증명 대리 주입, SMT 정책 증명기(openshell-prover) 심층 해부와 박스 실측

코딩 에이전트에게 셸을 열어 주는 순간, 질문은 “무엇을 할 수 있나”에서 “무엇을 못 하게 할 수 있나”로 바뀐다. 패키지를 설치하고 API를 부르고 토큰을 써야 쓸모가 있지만, 그 토큰이 env 한 줄로 새거나 프롬프트 인젝션 한 번에 엉뚱한 호스트로 나가면 끝이다. NVIDIA/OpenShell은 이 문제를 “에이전트에게 열쇠를 주지 말고, 문지기에게 맡겨라”라는 구조로 푼다. 에이전트는 커널 수준으로 격리된 샌드박스 안에서 돌고, 바깥으로 나가는 모든 TCP·DNS는 신뢰 구역의 슈퍼바이저가 정책으로 판정한 뒤 대신 연결한다. 진짜 API 키는 샌드박스 안에 아예 없고, 허용된 목적지로 가는 요청에만 슈퍼바이저가 끼워 넣는다. 여기에 정책 변경이 무엇을 새로 허용하는지 SMT 솔버로 미리 증명하는 openshell-prover가 붙는다.

오늘(2026-10-23) GitHub Trending Rust 일간 3위(+211, 11:52 KST 스냅숏)에 올랐다. 지난주 Tuesday 정기 릴리스인 v0.1.5(10/21 02:28 KST)가 나왔고, 0.1.x부터 “안정 릴리스 주기”를 선언한 직후라 실무 도입을 검토하는 팀이 늘어난 시점이다. 이 글은 저장소 코드와 문서, 릴리스 노트를 기준으로 구조와 타협점을 해부하고, 박스(리눅스 x86_64 VM, 8코어, 커널 6.12)에서 v0.1.5 릴리스 바이너리를 SHA-256 검증 후 받아 정책 증명기 13개 케이스 + 규모 테스트를 직접 돌린 결과를 적는다. 박스에는 Docker/Podman이 없어 실제 샌드박스 생성은 하지 않았다(아래에 정확히 무엇을 돌렸고 무엇을 안 돌렸는지 표로 정리).

한눈에 보기: 오늘 기준 스냅숏

왜 지금 뜨나: “샌드박스”가 아니라 “에이전트 함대 런타임”

에이전트 샌드박스는 이미 많다. Codex CLI와 Claude Code는 OS 샌드박스를 내장했고, E2B·Daytona 같은 호스팅형도 있으며, 이 블로그에서 10월 11일 다룬 microsoft/mxc는 앱에 넣는 크로스 플랫폼 격리 SDK였다. OpenShell이 노리는 층은 그 위다. README 첫 문장이 “safe, private runtime for fleets of autonomous AI agents”다. 즉 한 개발자의 터미널이 아니라 여러 에이전트를 여러 런타임(Docker·Podman·Kubernetes·MicroVM)에서 같은 정책으로 돌리는 컨트롤 플레인이다. 지금 주목받는 이유를 정리하면 세 가지다.

아키텍처: 게이트웨이 · 슈퍼바이저 · 샌드박스

핵심은 판정하는 쪽과 실행되는 쪽을 물리적으로 갈라 놓은 것이다. 문서(docs/about/architecture.mdx)의 구성 요소를 책임 기준으로 다시 묶으면 다음과 같다.

샌드박스와 슈퍼바이저는 OpenShell Sandbox Protocol, 즉 상호 인증된 HTTP/2 연결 하나 위의 여러 스트림으로 대화한다. TCP 연결마다 별도 스트림과 백프레셔가 있어서 느린 다운로드가 DNS나 exec를 막지 않는다. 전송 계층은 드라이버가 고른다.

네트워크 요청 한 건의 여정

세부 동작 중 운영자가 알아야 할 것들: 루프백(127/8)·링크 로컬(169.254/16, 클라우드 메타데이터 포함)·0.0.0.0은 정책과 무관하게 항상 차단되고 allowed_ips로도 열 수 없다. 바이너리는 심볼릭 링크가 아닌 커널이 보고하는 실경로로 매칭하므로 Ubuntu 24.04에서 pip 규칙은 /usr/bin/python3.12를 적어야 한다. 처음 연결에 참여한 실행 파일의 해시를 기록해 두고, 그 경로의 파일이 바뀌면 이후 연결을 거부한다. 슈퍼바이저와의 연결이 끊기면 샌드박스는 에이전트를 얼리고, 같은 슈퍼바이저 프로세스만 재접속해 재개할 수 있다.

인증: 토큰은 모두 ‘샌드박스 하나, 실행 한 번’에 묶인다

정책 모델: 다섯 섹션, 두 개의 적용 시점

정책이 없으면 쓰는 기본 정책은 꽤 빡빡하다. 작업 디렉터리 읽기쓰기, /bin /usr /lib /proc /etc /var/log /dev/urandom 읽기, /tmp·/dev/null 쓰기, 네트워크 규칙 0개 = 외부 전부 거부. Docker/Podman은 이미지 USER가 root면 정책에서 non-root를 지정하지 않는 한 거부한다. 그리고 /.openshell 사설 디렉터리는 Landlock ABI v3 필수 베이스라인으로 보호되며 best_effort로도 끌 수 없다. 우선순위는 글로벌 정책 → 샌드박스 저장 정책(--policy) → 이미지 내장 정책 → 기본 정책이고, 이미지 정책이 깨져 있으면 기본값으로 떨어지지 않고 시작 자체를 거부한다(fail closed).

# 읽기 전용 GitHub API 규칙을 실행 중인 샌드박스에 추가 (문서 예시)
openshell policy update my-sandbox \
  --rule-name github_readonly \
  --binary /usr/bin/curl \
  --add-endpoint api.github.com:443:read-only:rest:enforce \
  --wait

# 같은 규칙의 YAML 형태
network_policies:
  github_readonly:
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce     # 기본값은 audit(로그만)
        access: read-only        # GET / HEAD / OPTIONS
    binaries:
      - path: /usr/bin/curl

Providers: 키는 게이트웨이에, 샌드박스엔 플레이스홀더

Provider는 “서비스 이름 ↔ 저장된 자격 증명”이고, provider 프로필이 그 자격 증명이 갈 수 있는 호스트·포트·경로·바이너리를 정의한다. 저장소 providers/에는 anthropic, openai, nvidia, openrouter, github, aws, aws-bedrock, google-vertex-ai, oci-genai, pypi, claude-code, codex, copilot, cursor 등 예시 프로필이 있다. 예컨대 github.yaml은 GITHUB_TOKEN/GH_TOKEN을 api.github.com REST·GraphQL 읽기 전용과 github.com clone/fetch에만 보내고 push(git-receive-pack)는 막는 형태다. 파일 머리말이 “그대로 import하지 말고 binaries를 당신 이미지의 경로로 고쳐라”라고 못 박아 둔 점이 인상적이다.

# 로컬 환경변수에서 키를 읽어 provider 생성 → 샌드박스에 붙이기
export ANTHROPIC_API_KEY=sk-ant-...        # 게이트웨이에만 저장됨
openshell provider create --name my-claude --type claude-code --from-existing
openshell sandbox create --name dev --provider my-claude --policy ./policy.yaml

# 프로필 확인 / 커스텀 프로필 검사
openshell profile list
openshell profile describe github
openshell provider profile lint -f providers/github.yaml

Policy advisor와 prover: 사람 승인 앞에 기계 검사

Policy advisor는 기본 꺼짐이다. 켜면(agent_policy_proposals_enabled=true) 샌드박스 안에 /etc/openshell/skills/policy_advisor.md와 SKILL.md, (없으면) /AGENTS.md가 생기고, 샌드박스 안에서만 닿는 http://policy.local API로 에이전트가 거부 내역을 보고 좁은 규칙을 제안한다. 제안은 절대 스스로 적용되지 않는다. 게이트웨이는 제안마다 proposal risk check(prover로 “이 규칙이 있을 때와 없을 때 도달 가능 범위 차이”를 계산)와 휴리스틱(사설 IP, 와일드카드 호스트, 링크 로컬 등)을 돌리고, 발견이 하나라도 있으면 자동 승인을 막는다. advisor를 꺼도 OpenShell은 차단된 연결로부터 “바이너리 1개 → 호스트:포트 1개” 초안을 스스로 만든다.

별도 바이너리 openshell-prover는 boundary check를 한다. 운영자가 쓴 “최대 허용 범위” 정책(boundary) 안에 후보 정책(candidate)이 들어가는지 Z3(SMT)로 검사한다. 게이트웨이 없이 파일만 읽으므로 CI 게이트나 “부모 에이전트가 서브에이전트용 정책을 쓸 때 자기 범위를 넘지 않는지” 확인하는 용도로 설계됐다. 두 검사는 서로 다른 질문이라, 하나를 통과해도 다른 하나는 실패할 수 있다고 문서가 분명히 한다.

박스 실측 ①: openshell-prover 13개 케이스

환경: v0.1.5 openshell-prover-x86_64-unknown-linux-musl.tar.gz(14.6MB → 바이너리 32.9MB, static), 체크섬 파일과 SHA-256 일치(79e6c13d…0914). CLI(openshell 26.5MB, ca1ad6e6…af69)도 같은 방식으로 검증. 격리 HOME, OPENSHELL_TELEMETRY_ENABLED=false. 경계 정책은 “/usr /etc /lib 읽기 + /tmp 쓰기, Landlock hard_requirement, 사용자 sandbox, curl → api.github.com:443 REST 읽기 전용(enforce), python3.12 → pypi.org·files.pythonhosted.org:443”으로 잡고, 후보를 한 군데씩 바꿨다.

openshell-prover check --boundary boundary.yaml c03-rest-readwrite.yaml
result: exceeds_boundary
coverage: domains=filesystem,network_l4,network_rest,process,landlock
counterexample: network binary=- ancestor_binary=- binary_identity_required=false
  host=api.github.com:443 destination_ip=::1:0:0 trusted_gateway=false
  protocol=rest method=PUT path=/

박스 실측 ②: 규칙 수와 증명 시간

실무 정책은 13줄짜리가 아니다. 그래서 REST 읽기 전용 규칙 N개짜리 경계와, 그중 0.8N개를 쓰는 후보(within) / 거기에 read-write 규칙 1개를 더한 후보(exceeds)를 생성해 시간을 쟀다(--timeout 60s, 8코어 VM, 단일 실행).

규칙 수에 대해 대략 선형보다 약간 가파르게 늘고, exceeds가 within보다 빠르다(반례 하나만 찾으면 끝나니까). 기본 타임아웃 10초에서는 수백 규칙대에서 inconclusive가 나온다. 게이트웨이의 proposal risk check는 “현재 정책 + 제안 1건”이라 규모가 다르지만, CI에서 회사 전체 boundary를 검사한다면 --timeout을 명시하고 --output json의 reason_code(solver_timeout, resource_limit 등)로 분기하는 게 맞다. 측정은 합성 정책 한 종류·1회 실행 기준이라 절대값보다는 경향으로 보길 권한다.

# CI 게이트 예시: 샌드박스의 유효 정책이 조직 boundary 안에 있는지
openshell sandbox get my-sandbox --policy-only > candidate.yaml
openshell-prover check candidate.yaml --boundary org-boundary.yaml \
  --output json --timeout 60s > prover.json
jq -e '.result == "within_boundary"' prover.json   # 그 외 결과는 모두 실패 처리
jq -r '.reason_code // .counterexample' prover.json

박스 실측 ③: 돌린 것과 못 돌린 것

# 박스에서 실제로 쓴 명령 (요약)
B=https://github.com/NVIDIA/OpenShell/releases/download/v0.1.5
curl -sSLO $B/openshell-prover-x86_64-unknown-linux-musl.tar.gz
curl -sSLO $B/openshell-prover-checksums-sha256.txt
sha256sum -c --ignore-missing openshell-prover-checksums-sha256.txt
tar -xzf openshell-prover-x86_64-unknown-linux-musl.tar.gz
export OPENSHELL_TELEMETRY_ENABLED=false HOME=$PWD/home
./openshell-prover check --boundary boundary.yaml c01-within.yaml; echo $?

# 일반적인 설치 (공식 Quickstart) — Docker/Podman/가상화가 있는 호스트
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | OPENSHELL_VERSION=v0.1.5 sh
openshell sandbox create --name demo

저장소 구조: 어디부터 읽을까

흥미로운 점은 저장소 자체가 “agent-first”로 개발된다는 것이다. AGENTS.md, CLAUDE.md, .agents/skills/에 triage·release·security-fix용 스킬 20여 개가 있고, npx skills add NVIDIA/OpenShell로 사용자 에이전트에게 CLI 사용법·정책 작성·게이트웨이 디버깅 스킬을 설치할 수 있다. 에이전트에게 정책 YAML 초안을 쓰게 하고 prover로 검사하는 흐름이 의도된 사용 방식이다.

대안과 비교

타협점과 주의 사항

도입 체크리스트

정리

OpenShell의 가치는 “또 하나의 샌드박스”가 아니라 판정과 실행의 분리, 자격 증명을 샌드박스 밖에 두는 치환 모델, 정책 변경을 SMT로 검사하는 습관 세 가지에 있다. 박스에서 돌려 본 prover는 빠르고(수십 ms), 판단할 수 없는 것은 솔직하게 unsupported로 돌려주며, 수백 규칙대에선 타임아웃을 명시해야 했다. 반면 진짜 이점인 런타임 집행은 Docker/Podman/K8s/KVM 위의 게이트웨이까지 올려야 체감할 수 있고, 커널·CNI·TLS 종단이라는 운영 비용이 따라온다. 에이전트 한두 개를 노트북에서 돌리는 팀에겐 과하고, 여러 팀의 에이전트를 같은 정책·같은 감사 로그로 묶어야 하는 조직에겐 지금 오픈소스로 볼 수 있는 가장 완결된 설계 중 하나다. 시작은 prover 하나를 CI에 넣는 것부터가 가장 싸다.