NVIDIA/OpenShell

OpenShell은 자율형 AI 에이전트 (autonomous AI agents)를 위한 안전하고 프라이빗한 런타임 (runtime)입니다. 이는 데이터, 자격 증명 (credentials), 인프라를 보호하는 샌드박스 실행 환경 (sandboxed execution environments)을 제공하며, 승인되지 않은 파일 접근, 데이터 유출 (data exfiltration), 통제되지 않은 네트워크 활동을 방지하는 선언적 YAML 정책 (declarative YAML policies)에 의해 관리됩니다.

OpenShell은 에이전트 우선 (agent-first) 방식으로 구축되었습니다. 이 프로젝트는 게이트웨이 트러블슈팅 (gateway troubleshooting)부터 정책 생성 (policy generation)에 이르기까지 모든 것을 위한 에이전트 기술 (agent skills)을 함께 제공하며, 기여자 (contributors)들이 이를 사용하기를 기대합니다.

알파 소프트웨어 — 싱글 플레이어 모드. OpenShell은 생존 증명 (proof-of-life) 단계입니다: 한 명의 개발자, 하나의 환경, 하나의 게이트웨이. 우리는 멀티 테넌트 기업 배포 (multi-tenant enterprise deployments)를 향해 나아가고 있지만, 시작점은 여러분만의 환경을 구축하고 실행하는 것입니다. 다듬어지지 않은 부분이 있을 수 있습니다. 여러분의 에이전트를 가져오세요.

지원되는 호스트 (A supported host)— macOS, WSL 2가 포함된 Windows, 또는 Linux.
로컬 런타임 (A local runtime)— MicroVM 기반 샌드박스를 위해 Docker, Podman, 또는 호스트 가상화 (host virtualization)가 활성화되어 있어야 합니다.

바이너리 (Binary, 권장):

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

PyPI에서 설치 (uv 필요):

uv tool install -U openshell

두 방법 모두 기본적으로 최신 안정 버전 (latest stable release)을 설치합니다. 특정 버전을 설치하려면 (binary의 경우) OPENSHELL_VERSION을 설정하거나, uv tool install openshell==<version>으로 버전을 고정하세요. main 브랜치의 최신 커밋을 추적하는 dev 릴리스 (release)도 사용할 수 있습니다.

Helm 차트 (Helm chart):

실험적 단계 — Kubernetes 배포 경로는 현재 활발히 개발 중입니다. 다듬어지지 않은 부분과 중대한 변경 사항 (breaking changes)이 있을 수 있습니다.

GHCR에 게시된 OCI 차트를 사용하여 Kubernetes 클러스터에 OpenShell 게이트웨이를 배포하세요:

helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart

사용 가능한 버전, dev 태그 관례 및 구성에 대해서는 deploy/helm/openshell/README.md를 참조하세요.

OpenShift에 OpenShell을 배포하려면 deploy/helm/openshell/README.md#install-on-openshift를 참조하세요.

openshell sandbox create -- claude # 또는 opencode, codex, copilot

샌드박스 컨테이너에는 기본적으로 다음 도구들이 포함됩니다:

카테고리 (Category)	도구 (Tools)
에이전트 (Agent)	claude , opencode , codex , copilot
...

자세한 내용은 https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base 를 참조하세요.

모든 샌드박스 (sandbox)는 **최소한의 외부 접속 권한 (minimal outbound access)**으로 시작합니다. 아무것도 재시작하지 않고도, 프록시 (proxy)가 HTTP 메서드 및 경로 수준에서 강제하는 짧은 YAML 정책 (policy)을 통해 추가적인 접속 권한을 열 수 있습니다.

# 1. 샌드박스 생성 (최소한의 외부 접속 권한으로 시작)
openshell sandbox create
# 2. 샌드박스 내부 — 차단됨
...

전체 가이드를 확인하거나 자동화된 데모를 실행하세요:

bash examples/sandbox-policy-quickstart/demo.sh

OpenShell은 정책이 강제되는 이그레스 라우팅 (egress routing)을 통해 각 샌드박스를 자체 컨테이너 (container) 내에 격리합니다. 경량 게이트웨이 (gateway)가 샌드박스의 생명주기 (lifecycle)를 조정하며, 모든 외부 연결은 정책 엔진 (policy engine)에 의해 가로채어 다음 세 가지 중 하나를 수행합니다:

허용 (Allows)— 목적지와 바이너리 (binary)가 정책 블록과 일치합니다.
추론을 위한 라우팅 (Routes for inference)— 호출자의 자격 증명 (credentials)을 제거하고, 백엔드 자격 증명을 주입하여 관리되는 모델 (managed model)로 전달합니다.
거부 (Denies)— 요청을 차단하고 로그를 기록합니다.

구성 요소 (Component)	역할 (Role)
게이트웨이 (Gateway)	샌드박스 생명주기를 조정하고 인증 경계 (auth boundary) 역할을 하는 컨트롤 플레인 (Control-plane) API
샌드박스 (Sandbox)	컨테이너 감독 (container supervision) 및 정책이 강제되는 이그레스 라우팅을 갖춘 격리된 런타임 (runtime)
정책 엔진 (Policy Engine)	애플리케이션 계층부터 커널 (kernel)에 이르기까지 파일 시스템, 네트워크 및 프로세스 제약 조건을 강제함
프라이버시 라우터 (Privacy Router)	민감한 컨텍스트를 샌드박스 컴퓨팅 내에 유지하는 프라이버시 인식형 LLM 라우팅

OpenShell은 구성된 컴퓨팅 드라이버 (compute driver)를 통해 샌드박스 생명주기를 관리하는 게이트웨이 컨트롤 플레인을 실행합니다. 지원되는 컴퓨팅 플랫폼에는 Docker, Podman, MicroVM 및 Kubernetes가 포함됩니다.

OpenShell은 네 가지 정책 도메인에 걸쳐 심층 방어 (defense in depth)를 적용합니다:

계층 (Layer)	보호 대상	적용 시점
파일 시스템 (Filesystem)	허용된 경로 외부의 읽기/쓰기 방지	샌드박스 생성 시 잠김
...

정책은 선언적 YAML 파일입니다. 정적 섹션 (파일 시스템, 프로세스)은 생성 시 잠기며, 동적 섹션 (네트워크, 추론)은 openshell policy set 명령어를 통해 실행 중인 샌드박스에 핫 리로드 (hot-reload)할 수 있습니다.

에이전트(Agents)에는 API 키, 토큰, 서비스 계정(service accounts)과 같은 자격 증명(credentials)이 필요합니다. OpenShell은 이를 **프로바이더 (providers)**로 관리합니다. 프로바이더는 샌드박스 생성 시 주입되는 이름이 지정된 자격 증명 번들입니다. CLI는 사용자의 쉘 환경으로부터 인식된 에이전트(Claude, Codex, OpenCode, Copilot)에 대한 자격 증명을 자동으로 탐색하거나, openshell provider create를 통해 명시적으로 프로바이더를 생성할 수 있습니다. 자격 증명은 샌드박스 파일 시스템으로 절대 유출되지 않으며, 런타임(runtime) 시 환경 변수로 주입됩니다.

실험적 기능— GPU 패스스루 (passthrough)는 지원되는 호스트에서 작동하지만 현재 활발히 개발 중입니다. 미흡한 점이나 중대한 변경 사항(breaking changes)이 발생할 수 있습니다.

OpenShell은 로컬 추론 (inference), 미세 조정 (fine-tuning) 또는 기타 GPU 워크로드를 위해 호스트 GPU를 샌드박스로 전달할 수 있습니다. 샌드박스를 생성할 때 --gpu 옵션을 추가하세요:

openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude

Docker 기반 GPU 샌드박스는 CDI를 사용할 수 있는 경우 자동으로 선택하며, 그렇지 않으면 Docker의 NVIDIA GPU 요청 경로(--gpus all)로 폴백 (fallback)합니다. 이름에 gpu가 포함된 커뮤니티 이미지의 경우 GPU 의도(intent)가 자동으로 추론됩니다.

요구 사항: 호스트에 NVIDIA 드라이버와 NVIDIA Container Toolkit이 설치되어 있어야 합니다. 샌드박스 이미지 자체에는 워크로드에 적합한 GPU 드라이버와 라이브러리가 포함되어 있어야 합니다. 기본 base 이미지에는 포함되어 있지 않습니다. GPU 지원을 갖춘 커스텀 샌드박스 이미지를 빌드하는 방법은 BYOC 예제를 참조하세요.

에이전트 (Agent)	소스 (Source)	비고 (Notes)
Claude Code	base	즉시 사용 가능. 프로바이더 (Provider)가 ANTHROPIC_API_KEY를 사용합니다.
OpenCode	base	즉시 사용 가능. 프로바이더 (Provider)가 OPENAI_API_KEY 또는 OPENROUTER_API_KEY를 사용합니다.
Codex	base	즉시 사용 가능. 프로바이더 (Provider)가 OPENAI_API_KEY를 사용합니다.
GitHub Copilot CLI	base	즉시 사용 가능. 프로바이더 (Provider)가 GITHUB_TOKEN 또는 COPILOT_GITHUB_TOKEN을 사용합니다.
OpenClaw	NemoClaw	NemoClaw를 사용한 관리형 추론 (managed inference)을 통해 NVIDIA OpenShell 내부에서 OpenClaw를 더 안전하게 실행합니다.
Ollama	Community	openshell sandbox create --from ollama 명령으로 실행합니다.
Pi	Community	openshell sandbox create --from pi 명령으로 실행합니다.

명령 (Command)	설명 (Description)
openshell sandbox create -- <agent>	샌드박스 (sandbox)를 생성하고 에이전트 (agent)를 실행합니다.
openshell sandbox connect [name]	실행 중인 샌드박스 (sandbox)에 SSH로 접속합니다.
openshell sandbox list	모든 샌드박스 (sandbox) 목록을 표시합니다.
openshell provider create --type [type]] --from-existing	환경 변수 (env vars)로부터 자격 증명 프로바이더 (credential provider)를 생성합니다.
openshell policy set <name> --policy file.yaml	실행 중인 샌드박스 (sandbox)에 정책 (policy)을 적용하거나 업데이트합니다.
openshell policy get <name>	활성화된 정책 (policy)을 보여줍니다.
openshell inference set --provider <p> --model <m>	inference.local 엔드포인트 (endpoint)를 구성합니다.
openshell logs [name] --tail	샌드박스 (sandbox) 로그를 스트리밍합니다.
openshell term	디버깅을 위한 실시간 터미널 UI를 실행합니다.

명령 가이드, 튜토리얼 및 참고 자료에 대한 전체 문서를 확인하세요.

OpenShell은 k9s에서 영감을 받은 게이트웨이 (gateways), 샌드박스 (sandboxes) 및 프로바이더 (providers) 모니터링을 위한 실시간 터미널 대시보드를 포함하고 있습니다.

openshell term

TUI (Terminal User Interface)는 게이트웨이 (gateway)와 샌드박스 (sandboxes)에 대한 실시간 키보드 기반 뷰를 제공합니다. Tab으로 패널을 전환하고, j / k로 목록을 이동하며, Enter로 선택하고, :로 명령 모드 (command mode)를 사용하세요. 게이트웨이 상태 (Gateway health)와 샌드박스 상태 (sandbox status)는 2초마다 자동으로 새로고침됩니다.

--from을 사용하세요.

OpenShell 커뮤니티 카탈로그, 로컬 디렉토리 또는 컨테이너 이미지(container image)로부터 샌드박스(sandbox)를 생성하려면 --from을 사용하세요:

openshell sandbox create --from gemini # 커뮤니티 카탈로그
openshell sandbox create --from ./my-sandbox-dir # 로컬 Dockerfile
openshell sandbox create --from registry.io/img:v1 # 컨테이너 이미지

자세한 내용은 커뮤니티 샌드박스 카탈로그와 BYOC 예제를 참조하세요.

저장소(repo)를 클론(Clone)하고 코딩 에이전트(coding agent)가 이를 가리키도록 설정하세요. 이 프로젝트에는 질문에 답하고, 워크플로(workflows)를 안내하며, 문제를 진단할 수 있는 에이전트 스킬(agent skills)이 포함되어 있어 별도의 이슈(issue) 등록이 필요하지 않습니다.

git clone https://github.com/NVIDIA/OpenShell.git # 또는 git@github.com:NVIDIA/OpenShell.git
cd OpenShell
# 에이전트가 이곳을 가리키게 하세요 — 그러면 .agents/skills/ 디렉토리의 스킬들을 자동으로 발견합니다.

에이전트는 CLI 사용(openshell-cli), 게이트웨이 트러블슈팅(debug-openshell-cluster), 추론(inference) 트러블슈팅(debug-inference), 정책 생성(generate-sandbox-policy) 등을 위한 스킬을 로드할 수 있습니다. 전체 스킬 테이블은 CONTRIBUTING.md를 참조하세요.

OpenShell은 자체적으로 지원하는 것과 동일한 에이전트 주도 워크플로(agent-driven workflows)를 사용하여 개발됩니다. .agents/skills/ 디렉토리에는 프로젝트의 개발 사이클을 구동하는 워크플로 자동화(workflow automation)가 포함되어 있습니다:

Spike 및 빌드(Spike and build): create-spike로 문제를 조사한 다음, 사람이 승인하면 build-from-issue로 구현합니다.
트리아지 및 라우팅(Triage and route): 커뮤니티 이슈는 triage-issue로 평가 및 분류되어 spike-build 파이프라인으로 라우팅됩니다.
보안 검토(Security review): review-security-issue가 심각도 평가 및 해결 계획을 생성하며, fix-security-issue가 이를 구현합니다.
정책 작성(Policy authoring): generate-sandbox-policy가 자연어 요구사항이나 API 문서로부터 YAML 정책을 생성합니다.

모든 구현 작업은 사람에 의해 제어됩니다(human-gated). 에이전트가 계획을 제안하면, 사람이 승인하고, 에이전트가 빌드합니다. 전체 워크플로 체인 문서(workflow chain documentation)는 AGENTS.md를 참조하세요.

질문 및 토론: GitHub Discussions
버그 보고: GitHub Issues — 버그 보고 템플릿을 사용하세요
보안 취약점: SECURITY.md 참조 — GitHub Issues를 사용하지 마세요
에이전트 지원 도움말: 저장소를 클론(Clone)하고 .agents/skills/에 있는 에이전트 기술(agent skills)을 사용하여 셀프 서비스 진단을 수행하세요.

• 전체 문서 (Full Documentation) — 개요, 아키텍처 (Architecture), 튜토리얼 (Tutorials) 및 참조 (Reference)
• 퀵스타트 (Quickstart) — 상세 설치 및 첫 번째 샌드박스 (Sandbox) 워크스루 (Walkthrough)
• GitHub 샌드박스 튜토리얼 (GitHub Sandbox Tutorial) — 엔드 투 엔드 (End-to-end) 범위의 GitHub 저장소 액세스
• 아키텍처 (Architecture) — 상세 아키텍처 문서 및 설계 결정 사항
• 로드맵 (Roadmap) — 계획된 작업 및 프로젝트 우선순위
• 지원 매트릭스 (Support Matrix) — 플랫폼, 버전 및 커널 (Kernel) 요구 사항
• Brev Launchable — 로컬 설정 없이 클라우드 컴퓨팅에서 OpenShell 실행
• 에이전트 지침 (Agent Instructions) — 에이전트 기여자(Contributor)를 위한 시스템 프롬프트 (System prompt) 및 워크플로 (Workflow) 문서

OpenShell은 에이전트 우선(agent-first) 방식으로 구축되었습니다. 여러분의 에이전트가 여러분의 첫 번째 협업자입니다. 이슈(Issue)를 생성하거나 코드를 제출하기 전에, 에이전트가 이 저장소를 가리키게 하여 .agents/skills/에 있는 기술을 사용하여 조사, 진단 및 프로토타이핑 (Prototype)을 수행하도록 하세요. 전체 에이전트 기술 테이블, 기여 워크플로 및 개발 설정은 CONTRIBUTING.md를 참조하세요.

OpenShell은 개발자를 위한 프로젝트 개선을 돕기 위해 익명의 텔레메트리 (Telemetry)를 수집합니다. 이 데이터는 개별 사용자의 행동을 추적하는 데 사용되지 않습니다. 이는 샌드박스 (Sandbox), 프로바이더 (Provider) 및 정책 (Policy) 워크플로의 집계된 사용량을 이해하여 제품 개선의 우선순위를 정하고 사용 트렌드를 커뮤니티와 공유하는 데 도움이 됩니다.

게이트웨이 배포 시 OPENSHELL_TELEMETRY_ENABLED=false를 설정하여 텔레메트리를 비활성화할 수 있습니다.

OpenShell은 이 배포 설정을 샌드박스 감독 환경 (Sandbox supervisor environments)으로 전파하므로 샌드박스 측의 텔레메트리 수집도 함께 비활성화됩니다.

텔레메트리 (Telemetry) 이벤트는 샌드박스 생명주기 결과, 프로바이더 프로필 버킷 (provider profile buckets), 정책 결정 횟수, 그리고 집계된 네트워크 활동 거부 카테고리와 같이 익명의 운영 카테고리 및 수치로 제한됩니다. OpenShell 텔레메트리는 샌드박스 이름 또는 ID, 호스트 이름 (hostnames), 파일 경로, 바이너리 경로, 프롬프트 (prompts), 자격 증명 (credentials), 프로바이더 이름, 모델 이름 또는 사용자 콘텐츠를 수집하지 않습니다.

옵트아웃 (Opting out)은 OpenShell에서 방출되는 텔레메트리에만 적용됩니다. 귀하가 OpenShell과 함께 구성하여 사용하는 제3자 서비스, 모델 프로바이더 (model providers), 추론 엔드포인트 (inference endpoints), 에이전트 (agents) 또는 도구 (tools)는 자체적인 약관 및 개인정보 보호 관행을 가질 수 있습니다.

이 소프트웨어는 외부 자료를 자동으로 검색, 액세스 또는 상호작용합니다. 검색된 자료는 이 소프트웨어와 함께 배포되지 않으며, 별도의 약관, 조건 및 라이선스의 적용을 받습니다. 귀하는 모든 적용 가능한 약관, 조건 및 라이선스를 찾고, 검토하고, 준수할 책임과 귀하의 특정 사용 사례에 대한 검색된 자료의 보안, 무결성 및 적합성을 검증할 전적인 책임을 집니다. 이 소프트웨어는