OpenShell: AI 에이전트의 파일, 네트워크, 자격증명 접근을 선언형 정책으로 제한하는 NVIDIA 샌드박스 런타임

9bow · 10월 2, 2026, 3:00오전

핵심 요약

OpenShell은 AI 에이전트를 격리된 샌드박스에서 실행하고, 파일과 시스템 호출, 네트워크 연결을 YAML 정책으로 제한하는 NVIDIA의 오픈소스 런타임입니다.
에이전트는 실제 API 키 대신 의미 없는 플레이스홀더만 받고, 실제 키는 샌드박스 밖의 감독 프로세스가 정책이 허용한 엔드포인트로 가는 요청에만 채워 넣습니다.
정책 변경은 SMT(Satisfiability Modulo Theories) 솔버 기반 정책 증명기(Policy Prover)가 먼저 검사하며, 새로운 호스트에서의 자격증명 사용이나 새 HTTP 메서드 추가처럼 위험한 확장은 자동 승인되지 않고 사람의 검토를 기다립니다.
2026년 9월 말 공개된 0.1.0은 0.0.x에서 그대로 업그레이드할 수 없는 대규모 변경 릴리스이고, 2026년 10월 1일 기준 NemoClaw는 여전히 0.0.x의 마지막 릴리스인 OpenShell 0.0.116에 고정되어 있습니다.

OpenShell 소개

코딩 에이전트가 쓸모 있으려면 파일을 읽고, 패키지를 설치하고, API를 호출하고, 자격증명을 사용할 수 있어야 합니다. 같은 권한은 그대로 위험이 됩니다. 에이전트가 소스 코드를 허가되지 않은 서버로 올리거나, ~/.ssh의 키를 읽거나, 승인되지 않은 모델 제공자로 사내 데이터를 보낼 수 있기 때문입니다. 컨테이너에 넣는 것만으로는 이 문제가 풀리지 않습니다. 컨테이너 안에 API 키가 환경 변수로 들어가 있고 외부 네트워크가 열려 있다면, 에이전트는 그 키를 어디로든 보낼 수 있습니다. 이번에 소개하는 OpenShell은 NVIDIA가 이 문제를 겨냥해 공개한, 에이전트가 무엇에 접근할 수 있는지를 정책으로 선언하고 커널 수준에서 강제하는 에이전트용 샌드박스 런타임입니다.

OpenShell은 크게 2가지 방식으로 에이전트의 행동을 통제합니다: 하나는 실행 시점에 모든 파일 접근, 시스템 호출, 네트워크 연결을 커널 기능으로 검사하는 것이고, 다른 하나는 정책을 바꾸기 전에 형식 검증(Formal Verification)으로 그 변경이 무엇을 새로 허용하는지 확인하는 것입니다. 에이전트는 네트워크가 막힌 샌드박스 안에서만 돌고, 바깥으로 나가는 모든 요청은 샌드박스 밖에 있는 신뢰된 감독 프로세스인 슈퍼바이저(Supervisor)를 거칩니다. OpenShell에 따르면 에이전트는 실제 자격증명을 한 번도 보지 못합니다. 슈퍼바이저가 승인된 엔드포인트로 가는 요청에만 실제 값을 넣어 주기 때문입니다.

OpenShell은 Rust로 작성되어 있으며, 파일 접근 제한에는 리눅스 보안 모듈(LSM, Linux Security Module)인 Landlock을, 시스템 호출 제한과 네트워크 호출 가로채기에는 seccomp를 사용합니다. 샌드박스는 Docker, Podman, Kubernetes, libkrun 기반 마이크로VM(MicroVM) 위에서 만들 수 있고, 어느 런타임을 쓰든 요청을 허용할지는 같은 슈퍼바이저와 정책 엔진이 판단하도록 설계되어 있습니다. 관리용 CLI와 터미널 UI 외에 Python, TypeScript, Go, Rust SDK도 함께 제공합니다. OpenShell은 Claude Code, OpenCode, Codex, GitHub Copilot CLI 같은 코딩 에이전트를 파일과 네트워크 접근이 제한된 상태로 실행하는 것을 대표 사용 사례로 소개하고 있습니다.

OpenShell과 기존 방식 비교

OpenShell은 에이전트를 통제 없이 실행할 때 생기는 위험과 그에 대한 대응을 다음과 같이 정리하고 있습니다:

위협	통제 없이 실행할 때	OpenShell을 사용할 때
데이터 유출	에이전트가 소스 코드나 내부 파일을 허가되지 않은 엔드포인트로 올립니다.	네트워크 정책이 승인된 목적지만 허용하고 나머지 외부 연결은 모두 거부합니다.
자격증명 탈취	에이전트가 SSH 키나 클라우드 자격증명 같은 로컬 비밀값을 읽습니다.	Landlock 파일시스템 제한이 선언된 경로만 접근하게 합니다.
승인되지 않은 API 사용	에이전트가 승인되지 않은 모델 제공자로 프롬프트나 데이터를 보냅니다.	제공자 프로파일과 네트워크 정책이 모델 트래픽을 승인된 엔드포인트와 실행 파일로 제한합니다.
권한 상승	에이전트가 `sudo`나 setuid 경로, 위험한 시스템 호출을 시도합니다.	비특권 프로세스 신원과 seccomp 제한이 권한 상승 경로를 막습니다.

에이전트 샌드박스를 다루는 다른 오픈소스 프로젝트와 비교하면 OpenShell이 다루는 범위가 더 잘 보입니다. 아래 표는 PyTorchKR에서 소개한 두 프로젝트를 각 저장소가 밝힌 범위 기준으로 나란히 놓은 것입니다:

항목	Sandbox Runtime(srt)	OneCLI v2	OpenShell
주된 역할	임의의 프로세스에 파일과 네트워크 제한을 거는 경량 샌드박스	팀원마다 샌드박스 에이전트를 만들어 주는 팀용 에이전트 하네스(대화, 메모리, Slack 연동 포함)	사용자가 가져온 에이전트의 샌드박스 수명 주기, 정책, 자격증명을 관리하는 런타임
격리 수단	OS 기본 샌드박스(macOS `sandbox-exec`, 리눅스 `bubblewrap`), 컨테이너 불필요	에이전트마다 격리된 샌드박스, 바깥으로 나가는 길은 게이트웨이뿐	네트워크가 막힌 컨테이너, 파드, 마이크로VM + Landlock, seccomp
자격증명 처리	주요 기능 목록에 없음	게이트웨이가 호스트와 경로 패턴에 맞춰 헤더나 쿼리 파라미터로 주입	플레이스홀더를 실제 키로 교체하되, 제공자 프로파일이 허용한 호스트, 포트, 경로에서만

srt가 한 프로세스를 가볍게 가두는 도구라면, OneCLI는 자격증명 저장소로 출발해 v2에서 에이전트 자체까지 포함한 팀용 하네스가 되었습니다(PyTorchKR의 OneCLI 글은 v1 기준입니다). OpenShell은 에이전트를 포함하지 않고 사용자가 가져온 에이전트를 가두는 런타임으로, 샌드박스와 자격증명 주입을 하나의 제어 평면(Control Plane) 아래로 묶고 정책 변경을 검증하는 정책 증명기를 더했습니다. 그만큼 설치하고 운영할 구성 요소도 많습니다. 참고로 srt는 Anthropic이 연구 프리뷰(Beta Research Preview)로 공개한 상태입니다.

OpenShell과 NemoClaw의 관계

PyTorchKR에서 앞서 소개한 NVIDIA NemoClaw는 OpenShell 위에서 동작하는 레퍼런스 스택입니다. NVIDIA는 NemoClaw 문서에서 OpenShell을 샌드박스와 정책 엔진으로, NemoClaw를 그 위에서 강화된 이미지, 기본 정책, 온보딩, 스냅샷과 복원 같은 수명 주기 도구를 제공하는 계층으로 구분합니다. 정리하면 OpenClaw 같은 정해진 에이전트를 NVIDIA 기본값으로 빠르게 실행하려면 NemoClaw가, 자체 이미지와 정책으로 사내 플랫폼을 구성하려면 OpenShell 직접 사용이 맞다는 것이 NVIDIA의 안내입니다.

주의할 점은 버전입니다. 2026년 10월 1일 기준 NemoClaw 저장소의 blueprint.yaml은 min_openshell_version과 max_openshell_version을 모두 0.0.116으로 고정하고 있습니다. NemoClaw 온보딩이 설정하는 OpenShell 추론 라우팅(Inference Routing)과, NemoClaw 문서가 비교 대상으로 든 openshell sandbox create --from openclaw의 이미지 빌드는 모두 OpenShell 0.1.0에서 제거되었습니다. NemoClaw를 쓰고 있다면 NemoClaw가 지원 버전을 올리기 전까지 OpenShell을 0.1.x로 따로 업그레이드하지 않는 것이 안전합니다.

OpenShell을 사용하면 좋을 사용자

OpenShell은 코딩 에이전트에게 GitHub 토큰이나 모델 API 키를 쥐여 주어야 하는 팀, 그리고 여러 에이전트를 Kubernetes 클러스터에서 공용으로 운영하면서 정책을 버전 관리와 감사 대상으로 다루고 싶은 플랫폼 팀에 맞습니다. 리눅스(Debian/Ubuntu, amd64와 arm64)와 Apple Silicon macOS가 정식 지원 대상이고, --gpu로 GPU를 요청하는 샌드박스도 만들 수 있습니다. 정책 어드바이저와 정책 증명기는 에이전트가 필요한 접근을 스스로 요청하고 사람이 승인하는 흐름을 전제로 하므로, 에이전트 작업이 처음부터 모든 목적지를 알기 어려운 경우에 특히 쓸모가 있습니다.

반대로 Windows 네이티브 환경은 아직 대상이 아닙니다. WSL(Windows Subsystem for Linux) 2는 실험 단계이고 Microsoft Execution Containers(MXC) 기반의 Windows 런타임은 "Coming soon" 으로 표기되어 있습니다. 샌드박스 경계에는 Landlock ABI 3(업스트림 리눅스 6.2에서 도입)과 seccomp 사용자 알림 기능이 필요하므로, 오래된 커널을 쓰는 서버에서는 먼저 지원 매트릭스를 확인해야 합니다. 개인 노트북에서 에이전트 하나만 가볍게 가두려는 사용자에게는 상시 실행되는 게이트웨이와 제공자 프로파일까지 관리해야 하는 OpenShell보다 srt 같은 경량 도구가 더 적절한 선택입니다.

OpenShell의 구조와 요청 경로

OpenShell은 제어 평면 역할의 게이트웨이(Gateway)와 데이터 평면 역할의 런타임으로 나뉩니다. 아래 그림은 OpenShell 문서의 시스템 구조도로, 왼쪽이 게이트웨이(GATEWAY, CONTROL PLANE), 가운데가 슈퍼바이저(Supervisor), 오른쪽이 네트워크가 격리된 샌드박스(SANDBOX, NETWORK ISOLATED), 아래쪽이 정책 수명 주기(POLICY LIFECYCLE)입니다:

샌드박스를 만들면 게이트웨이의 컴퓨트 드라이버(Compute Driver)가 에이전트가 돌 워크로드와 별도의 슈퍼바이저를 함께 생성하고, 둘 사이에 보호된 채널을 연결한 뒤 격리 경계를 만듭니다. 슈퍼바이저는 경계가 제대로 세워졌는지 확인한 다음에야 에이전트를 시작합니다. 각 구성 요소가 맡는 일은 다음과 같습니다:

샌드박스(Sandbox): 에이전트와 같은 경계 안에 있으면서 에이전트 프로세스를 소유하고, 각 요청을 어떤 프로그램이 보냈는지 /proc 정보로 식별해 TCP와 DNS 요청을 슈퍼바이저로 넘깁니다. 정책 판단은 하지 않습니다.
슈퍼바이저(Supervisor): 경계 바깥의 신뢰된 쪽에서 요청을 정책과 대조하고, 자격증명을 넣고, DNS를 해석하고, 승인된 연결만 실제로 엽니다.
게이트웨이(Gateway): 사용자 인증, 샌드박스 상태 저장, 정책과 설정 전달, 제공자 연결을 담당하며 정책 증명기도 여기서 실행됩니다.
제공자(Provider): 서비스 이름을 저장된 자격증명에 연결합니다. 슈퍼바이저는 정책이 허용한 곳에만 그 자격증명을 사용합니다.

에이전트가 네트워크 요청을 보내면 샌드박스가 호출한 프로그램을 식별하고, OpenShell 샌드박스 프로토콜(Sandbox Protocol)로 요청을 슈퍼바이저에 전달합니다. 슈퍼바이저가 정책을 확인해 허용되면 필요한 자격증명을 붙여 실제 연결을 열고 트래픽을 중계합니다. 아래 그림의 1~4번이 이 순서이고, 빨간 X 표시(ALL OTHER EGRESS DENIED)는 슈퍼바이저 채널을 제외한 모든 외부 연결이 막혀 있음을 나타냅니다:

이 채널은 상호 인증된 HTTP/2 연결 하나에 여러 스트림을 싣는 구조라서, 느린 다운로드가 DNS나 프로세스 제어를 막지 않습니다. 슈퍼바이저와의 연결이 끊기면 샌드박스는 에이전트를 멈추고, 같은 슈퍼바이저 프로세스만 다시 연결해 재개할 수 있습니다. 에이전트 쪽에는 게이트웨이 서명 키도, 제공자 자격증명도 없으므로 탈취할 만한 값이 남아 있지 않다는 것이 OpenShell의 설명입니다.

격리 경계를 만드는 방법은 런타임마다 다르지만, 요청을 허용할지는 언제나 공통 슈퍼바이저가 판단합니다. 런타임별 구현은 다음과 같습니다:

런타임	슈퍼바이저 위치	샌드박스와의 통신	직접 외부 연결을 막는 방법
Docker	별도 컨테이너	드라이버가 소유한 볼륨의 인증된 Unix 소켓	워크로드 컨테이너의 네트워크를 끔
Podman	별도 컨테이너	드라이버가 소유한 볼륨의 인증된 Unix 소켓	워크로드 컨테이너의 네트워크를 끔
Kubernetes	별도 파드	상호 TLS(mTLS)를 쓰는 사설 서비스	NetworkPolicy로 슈퍼바이저 서비스만 허용
마이크로VM	호스트의 프로세스	인증된 vsock	게스트에 네트워크 장치가 없음

OpenShell의 정책과 자격증명 주입

OpenShell의 정책은 version: 1과 최대 5개의 최상위 섹션으로 이루어진 YAML 파일입니다. 섹션마다 적용 시점이 다르다는 점이 중요합니다. 파일시스템(filesystem_policy), Landlock 호환성(landlock), 프로세스 신원(process)은 샌드박스가 시작될 때 고정되고, 네트워크 규칙(network_policies)과 미들웨어(network_middlewares)만 실행 중에 바꿀 수 있습니다. 전역 정책, 샌드박스에 저장된 정책, 이미지에 포함된 정책이 모두 없으면 작업 디렉토리와 /tmp, /dev/null에만 쓰기를 허용하고 외부 네트워크는 모두 막는 기본 정책이 적용됩니다.

네트워크 규칙은 목적지와 그 목적지에 접근할 수 있는 실행 파일을 함께 지정합니다. 아래는 OpenShell 튜토리얼의 예시로, curl만 GitHub API를 읽기 전용으로 쓸 수 있게 하는 규칙입니다:

network_policies:
  github_api:
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/bin/curl

이 규칙이 적용된 샌드박스에서 curl로 GET 요청을 보내면 통과하지만, 같은 호스트에 POST로 이슈를 만들려고 하면 슈퍼바이저가 HTTP 메서드를 검사해 403과 함께 policy_denied 응답을 돌려줍니다. 거부된 요청은 목적지, 호출한 실행 파일, 거부 사유와 함께 로그로 남습니다.

자격증명은 제공자(Provider)로 관리합니다. 에이전트 프로세스의 환경 변수에는 실제 값 대신 플레이스홀더 토큰이 들어가고, 에이전트가 그 플레이스홀더를 헤더나 쿼리 파라미터, URL 경로에 넣어 요청하면 프록시가 전송 직전에 실제 값으로 바꿉니다. 이때 네트워크 정책이 그 실행 파일과 목적지를 허용해야 하고, 제공자 프로파일이 그 호스트, 포트, 경로를 자격증명 사용처로 지정해야 하는 두 조건을 모두 만족해야 합니다. 예를 들어 GitHub 프로파일의 GITHUB_TOKEN은 api.github.com과 github.com에서만 실제 값으로 바뀌고, 정책이 다른 업로드 서버를 허용하더라도 그쪽으로 보내면 credential_endpoint_mismatch 사유로 403이 반환됩니다.

몇 가지 기본값은 직접 확인해야 합니다. protocol 필드가 없는 엔드포인트는 호스트, 포트, 실행 파일만 검사하고 HTTP 메서드와 경로는 모두 허용합니다. 요청 단위(L7) 검사를 켜더라도 enforcement의 기본값은 위반을 기록만 하고 통과시키는 audit이므로, 실제로 막으려면 enforce로 바꿔야 합니다. 또한 tls: skip으로 TLS 종료를 끈 엔드포인트에서는 자격증명 치환과 요청 검사가 모두 동작하지 않습니다.

OpenShell의 정책 증명기와 정책 어드바이저

OpenShell을 다른 샌드박스와 구분하는 기능은 정책을 바꾸는 과정에 붙은 두 도구입니다. 정책 증명기(Policy Prover)는 Z3 SMT 솔버로 정책이 특정 속성을 만족하는지 검사하는 엔진으로, 2가지 검사를 수행합니다: 하나는 후보 정책이 사용자가 정한 최대 허용 범위(Boundary)를 넘지 않는지 보는 경계 검사(Boundary Check)이고, 다른 하나는 새로 제안된 네트워크 규칙이 기존 정책보다 위험한 접근을 더하는지 보는 제안 위험 검사(Proposal Risk Check)입니다.

경계 검사는 openshell-prover CLI로 실행하며 게이트웨이 없이 로컬 정책 파일만 읽습니다. OpenShell은 부모 에이전트가 하위 에이전트용 정책을 만들 때 자신의 최대 허용 범위를 넘지 않는지 확인하거나, CI에서 정책 파일을 검사하는 용도를 예로 듭니다. 아래는 경계가 /usr와 /etc 읽기만 허용하는데 후보 정책이 /tmp 쓰기를 추가한 경우의 결과입니다:

openshell-prover check candidate.yaml --boundary boundary.yaml

result: exceeds_boundary
coverage: domains=filesystem,network_l4,network_rest,process,landlock
counterexample: filesystem write /tmp

결과는 within_boundary(종료 코드 0), exceeds_boundary(1), error(2), unsupported와 inconclusive(3) 중 하나이고, 통과로 볼 수 있는 것은 within_boundary뿐입니다. 정책 증명기가 검사하는 범위에는 분명한 한계가 있습니다. 현재 모델은 파일시스템, 프로세스 신원, Landlock 설정, L4 네트워크 연결, REST 요청만 다루고, GraphQL, MCP, WebSocket, JSON-RPC 규칙이 들어간 정책은 무시하지 않고 unsupported로 돌려줍니다. 경로가 서로 다르면 포함 관계여도 unsupported를 돌려주는데, 샌드박스 이미지 안의 심볼릭 링크가 /tmp/cache를 /tmp 밖으로 연결할 수 있기 때문입니다. OpenShell은 within_boundary가 경계를 넘지 않는다는 뜻일 뿐, 정책이 그 작업에 충분히 좁거나 안전하다는 뜻은 아니라고 명시하고 있습니다.

정책 어드바이저(Policy Advisor)는 이 증명기를 실제 운영 흐름에 연결합니다. 정책 어드바이저를 켜 두면 요청이 막힌 에이전트가 샌드박스 안에서만 열리는 http://policy.local API로 필요한 규칙을 직접 제안할 수 있고, OpenShell은 그 제안에 제안 위험 검사와 목적지 검사를 실행한 뒤 결과와 함께 대기 목록에 올립니다. 정책 어드바이저 자체는 기본으로 꺼져 있지만, 막힌 연결에서 실행 파일 하나와 호스트 하나, 포트 하나만 허용하는 초안 규칙을 만드는 기능은 모든 샌드박스에서 동작합니다. 제안 위험 검사가 잡아내는 항목은 다음과 같습니다:

검사 결과	제안된 규칙이 실행 파일에 새로 허용하는 것
`link_local_reach`	링크 로컬 주소(`169.254.0.0/16`, `fe80::/10`)나 클라우드 메타데이터 호스트 접근
`l7_bypass_credentialed`	자격증명이 있는 호스트로 `git`, `ssh`, `nc`처럼 검사할 수 없는 트래픽 전송
`credential_reach_expansion`	이전에는 닿지 않던 호스트와 포트에서 제공자 자격증명 사용
`capability_expansion`	이미 자격증명을 쓰는 호스트와 포트에서 새로운 HTTP 메서드 사용

승인 방식은 기본이 수동(manual)이고, 자동(auto) 모드를 켜면 위 검사 결과와 위험 목적지 표시가 하나도 없는 제안을 자동으로 승인합니다. 다만 OpenShell이 직접 경고하듯 자동 모드는 자격증명이 걸리지 않은 새로운 공개 호스트를 위험으로 보지 않으므로, 그 모드를 켜면 샌드박스 안의 실행 파일이 사람의 검토 없이 새 공개 호스트에 접근할 수 있게 됩니다. 루프백, 링크 로컬, 클라우드 메타데이터 주소는 어떤 경우에도 승인할 수 없습니다.

OpenShell 0.1.0의 변경점과 지원 환경

OpenShell은 2026년 2월 저장소를 연 뒤 0.0.x 버전을 거의 매일 자동으로 내보냈고(마지막은 2026년 8월 28일의 0.0.116), 2026년 9월 25일(UTC) 0.1.0부터 안정 릴리스 주기로 전환했습니다. 정식 릴리스는 보통 매주 화요일을 목표로 나오고, 최신 마이너 버전과 그 이전 마이너 버전(N-1)에 보안과 주요 안정성 수정을 제공합니다. 정식(Stable) API는 패치 릴리스 사이에서 하위 호환을 유지하고 깨지는 변경은 마이너 릴리스에서 안내와 이전 가이드를 함께 내지만, 실험(Experimental)으로 표시된 인터페이스는 패치 릴리스에서도 바뀌거나 사라질 수 있습니다. 전체 정책은 아직 검토(review) 상태인 RFC 0014에 정리되어 있습니다.

OpenShell은 0.1.0 업그레이드 가이드에서 로컬 0.0.x 설치를 제자리에서 업그레이드할 수 없다고 안내합니다. 기존 런타임을 정리하고 패키지를 제거한 뒤 새로 설치해야 하며, 기존 샌드박스도 모두 다시 만들어야 합니다. 기존 사용자가 특히 확인해야 할 변경은 다음과 같습니다:

관리형 추론 경로 제거: openshell inference 명령과 inference.local 엔드포인트가 사라졌습니다. 샌드박스마다 제공자를 연결하고 모델 제공자의 원래 API를 직접 호출해야 합니다.
내장 프로파일 제거: 게이트웨이에 기본 제공자 프로파일이 더 이상 들어 있지 않습니다. 저장소의 providers/ 디렉토리에 있는 예시 프로파일을 복사해 binaries 경로를 자기 이미지에 맞게 고친 뒤 가져와야 하며, 경로가 맞지 않으면 자격증명이 주입되지 않고 트래픽도 거부됩니다.
이미지 빌드 분리: openshell sandbox create --from이 더 이상 Dockerfile을 빌드하지 않으므로, 이미지를 먼저 빌드하고 그 참조를 넘겨야 합니다. 기본 워크로드 이미지는 에이전트가 설치되지 않은 최소 Ubuntu 24.04 이미지입니다.
정책 스키마 강화: 알 수 없는 필드나 오타가 있는 필드를 무시하지 않고 거부합니다.

지원 환경은 지원 매트릭스에 정리되어 있습니다. 런타임별로 Docker 28.0, Podman 5.x, Kubernetes 1.29와 Helm 3.x가 최소 버전이고, 마이크로VM은 macOS의 Hypervisor.framework나 리눅스의 KVM이 필요합니다. 커널은 리눅스 5.19 미만이면(RHEL 9.x와 RHCOS 등) 격리 경계는 그대로 유지하되 getpeername 같은 일부 소켓 호출이 EOPNOTSUPP로 실패하는 축소 모드(legacy read-only)로 동작하므로, 서버 역할을 하는 워크로드는 이 점을 확인해야 합니다. macOS에서는 이 커널 기능이 호스트가 아니라 Docker Desktop의 리눅스 VM 안에서 동작합니다.

OpenShell 설치와 사용

OpenShell은 설치 스크립트 하나로 CLI, 정책 증명기, 로컬 게이트웨이를 함께 설치합니다. macOS에서는 Homebrew 서비스로, Debian과 Ubuntu에서는 Debian 패키지, Fedora와 RHEL에서는 RPM 패키지로 설치되고 로컬 게이트웨이는 17670 포트에서 동작합니다. 설치와 첫 샌드박스 생성은 다음과 같습니다:

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell status
openshell sandbox create --name demo

기본 샌드박스 이미지에는 에이전트가 들어 있지 않습니다. 실제 에이전트를 실행하려면 제공자 프로파일을 가져오고, 자격증명을 저장하고, 에이전트가 설치된 이미지로 샌드박스를 만듭니다. 아래는 공식 문서의 예시로, OpenCode를 OpenRouter의 무료 모델로 실행합니다(사전에 OPENROUTER_API_KEY 환경 변수를 설정해 둡니다):

openshell profile import \
  --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml

openshell provider create \
  --name openrouter \
  --type openrouter \
  --from-existing

openshell sandbox create \
  --name my-agent \
  --from ghcr.io/anomalyco/opencode:latest \
  --provider openrouter \
  -- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free

에이전트가 정책에 없는 목적지에 접근하려 하면 OpenShell이 요청을 거부하고 초안 규칙을 만듭니다. 호스트에서 대기 중인 제안을 확인하고 승인하거나, 사유를 붙여 거절할 수 있습니다:

openshell rule get my-agent --status pending

openshell rule approve my-agent --chunk-id <chunk-id>

openshell rule reject my-agent \
  --chunk-id <chunk-id> \
  --reason "Not needed for this task."

승인된 규칙은 샌드박스를 재시작하지 않고 바로 반영됩니다. 이미 실행 중인 샌드박스에는 openshell policy update 명령으로 네트워크 규칙을 추가할 수 있고, 위 YAML 예시와 같은 규칙은 한 줄로 추가할 수 있습니다:

openshell policy update demo \
  --rule-name github_api \
  --binary /usr/bin/curl \
  --add-endpoint api.github.com:443:read-only:rest:enforce \
  --wait

코딩 에이전트에게 OpenShell 사용법을 가르치는 에이전트 스킬도 제공됩니다. npx skills add NVIDIA/OpenShell로 설치하면 에이전트가 OpenShell CLI 사용, 샌드박스 정책 작성, 게이트웨이와 추론 경로 디버깅을 할 수 있으며, 스킬 원본은 저장소의 skills/ 디렉토리에 있습니다. 애플리케이션에서 게이트웨이를 다루려면 Python SDK를 uv add openshell로 설치할 수 있습니다(TypeScript SDK는 GitHub Packages로 배포).

OpenShell은 익명 텔레메트리를 기본으로 수집합니다. 샌드박스 이름, 호스트 이름, 파일 경로, 프롬프트, 자격증명, 모델 이름은 수집하지 않는다고 밝히고 있으며, 게이트웨이에 OPENSHELL_TELEMETRY_ENABLED=false를 설정하거나 Helm 설치에서 server.telemetryEnabled=false를 지정해 끌 수 있습니다. 소스에서 빌드할 때는 텔레메트리 기능 자체를 컴파일에서 제외할 수도 있습니다.

OpenShell의 라이선스

OpenShell은 Apache-2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

OpenShell 공식 문서

OpenShell 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~