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

OpenShell은 에이전트 우선(agent-first)으로 설계되었습니다. OpenShell을 사용하고 운영하기 위한 공개 에이전트 스킬과 함께, 기여자와 유지관리자를 위한 별도의 저장소 인식 워크플로를 제공합니다.

빠른 시작

사전 요구 사항

• 지원되는 호스트 — Linux, macOS(Apple Silicon), 또는 WSL 2가 설치된 Windows(실험적).
• 로컬 런타임 — Docker, Podman, 또는 MicroVM 기반 샌드박스를 위한 호스트 가상화 활성화.

설치

바이너리(권장):```bash curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

설치 프로그램은 기본적으로 최신 안정 릴리스를 설치합니다. 특정 버전을 설치하려면 `OPENSHELL_VERSION`을 설정하세요. `main` 브랜치의 최신 커밋을 추적하는 [`dev` 릴리스](https://github.com/NVIDIA/OpenShell/releases/tag/dev)도 사용할 수 있습니다.

PyPI의 `openshell` 패키지는 Python SDK만 제공합니다. `openshell` CLI는 설치하지 않습니다. [uv](https://docs.astral.sh/uv/)를 사용하여 Python 프로젝트에 SDK를 추가하세요:```bash
uv add openshell

Helm 차트:

실험적 — Kubernetes 배포 경로는 현재 활발히 개발 중입니다. 거친 부분과 호환성을 깨는 변경이 있을 수 있습니다.

GHCR에 게시된 OCI 차트에서 OpenShell 게이트웨이를 Kubernetes 클러스터에 배포합니다:```bash helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart

사용 가능한 버전, dev 태그 규칙 및 구성에 대해서는 [`deploy/helm/openshell/README.md`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md)를 참조하십시오.

OpenShift에 OpenShell을 배포하려면 [`deploy/helm/openshell/README.md#install-on-openshift`](https://github.com/nvidia/openshell/blob/main/deploy/helm/openshell/README.md#install-on-openshift)를 참조하십시오.

### 샌드박스 생성```bash
openshell sandbox create -- claude  # or opencode, codex, copilot

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

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

네트워크 정책 실제 동작 확인

모든 샌드박스는 최소한의 아웃바운드 접근으로 시작합니다. 프록시가 HTTP 메서드와 경로 수준에서 강제 적용하는 짧은 YAML 정책을 통해 추가 접근을 열 수 있으며, 아무것도 재시작할 필요가 없습니다.```bash

1. Create a sandbox (starts with minimal outbound access)

openshell sandbox create

2. Inside the sandbox — blocked

sandbox$ curl -sS https://api.github.com/zen curl: (56) Received HTTP code 403 from proxy after CONNECT

3. Back on the host — apply a read-only GitHub API policy

sandbox$ exit openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait

4. Reconnect — GET allowed, POST blocked by L7

openshell sandbox connect demo sandbox$ curl -sS https://api.github.com/zen Anything added dilutes everything else.

sandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}' {"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}

[전체 워크스루](https://github.com/nvidia/openshell/blob/main/examples/sandbox-policy-quickstart)를 참조하거나 자동화된 데모를 실행하세요:```bash
bash examples/sandbox-policy-quickstart/demo.sh

작동 방식

OpenShell은 정책이 적용된 이그레스 라우팅을 통해 각 샌드박스를 자체 컨테이너에 격리합니다. 경량 게이트웨이가 샌드박스 수명 주기를 조정하며, 모든 아웃바운드 연결은 정책 엔진에 의해 가로채어지고, 정책 엔진은 다음 세 가지 중 하나를 수행합니다:

• 허용 — 목적지와 바이너리가 정책 블록과 일치합니다.
• 자격 증명을 엔드포인트에 바인딩 — 정책이 프로필 승인 엔드포인트에 대한 요청을 허용한 후에만 제공자 자격 증명을 주입합니다.
• 거부 — 요청을 차단하고 기록합니다.

OpenShell은 구성된 컴퓨트 드라이버를 통해 샌드박스 수명 주기를 관리하는 게이트웨이 컨트롤 플레인을 실행합니다. 지원되는 컴퓨트 플랫폼에는 Docker, Podman, MicroVM, Kubernetes가 있습니다.

보호 계층

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

정책은 선언적 YAML 파일입니다. 정적 섹션(파일 시스템, 프로세스)은 생성 시 잠기며, 네트워크 정책과 제공자 연결은 실행 중인 샌드박스에서 업데이트할 수 있습니다.

제공자

에이전트에는 자격 증명 — API 키, 토큰, 서비스 계정 — 이 필요합니다. OpenShell은 이를 제공자로 관리합니다: 생성 시 샌드박스에 주입되는 명명된 자격 증명 번들입니다. CLI는 셸 환경에서 인식된 에이전트(Claude, Codex, OpenCode, Copilot)의 자격 증명을 자동으로 검색하거나, openshell provider create로 제공자를 명시적으로 생성할 수 있습니다. 자격 증명은 샌드박스 파일 시스템으로 유출되지 않으며, 런타임에 환경 변수로 주입됩니다.

추론 액세스는 동일한 제공자 워크플로를 사용합니다. 추론 가능 제공자를 샌드박스에 연결하고, 제공자의 네이티브 엔드포인트를 호출한 다음, 클라이언트에서 모델을 선택합니다. 제공자 프로필은 엔드포인트 정책을 제공하고 자격 증명 자리 표시자를 승인된 목적지에 바인딩합니다.

GPU 지원 (실험적)

실험적 — GPU 패스스루는 지원되는 호스트에서 작동하지만 활발히 개발 중입니다. 거친 부분과 호환성을 깨는 변경이 있을 수 있습니다.

OpenShell은 로컬 추론, 파인튜닝 또는 모든 GPU 워크로드를 위해 호스트 GPU를 샌드박스로 전달할 수 있습니다. 샌드박스를 생성할 때 --gpu를 추가하세요:```bash openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude

Docker 기반 GPU 샌드박스는 사용 가능한 경우 CDI를 자동으로 선택하고, 그렇지 않으면 Docker의 NVIDIA GPU 요청 경로(`--gpus all`)로 폴백합니다.

**요구 사항:** NVIDIA 드라이버와 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)이 호스트에 설치되어 있어야 합니다. 샌드박스 이미지 자체에는 워크로드에 맞는 적절한 GPU 드라이버와 라이브러리가 포함되어야 합니다 — 기본 `base` 이미지에는 포함되어 있지 않습니다. GPU 지원이 포함된 사용자 정의 샌드박스 이미지를 빌드하는 방법은 [BYOC 예제](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)를 참조하세요.

## 지원되는 에이전트

| 에이전트                                                         | 소스                                                                           | 비고                                                                         |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 별도 설정 없이 바로 작동합니다. 프로바이더는 `ANTHROPIC_API_KEY`를 사용합니다.                      |
| [OpenCode](https://opencode.ai/)                              | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 별도 설정 없이 바로 작동합니다. 프로바이더는 `OPENAI_API_KEY` 또는 `OPENROUTER_API_KEY`를 사용합니다. |
| [Codex](https://developers.openai.com/codex)                  | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 별도 설정 없이 바로 작동합니다. 프로바이더는 `OPENAI_API_KEY`를 사용합니다.                         |
| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | 별도 설정 없이 바로 작동합니다. 프로바이더는 `GITHUB_TOKEN` 또는 `COPILOT_GITHUB_TOKEN`을 사용합니다. |
| [OpenClaw](https://openclaw.ai/)                 | [NemoClaw](https://github.com/NVIDIA/NemoClaw)                                   | NemoClaw 블루프린트를 사용하여 NVIDIA OpenShell 내부에서 OpenClaw를 더 안전하게 실행합니다.       |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent)   | [NemoClaw](https://github.com/NVIDIA/NemoClaw)                                   | NemoClaw 블루프린트를 사용하여 NVIDIA OpenShell 내부에서 Hermes Agent를 더 안전하게 실행합니다.   |
| [Ollama](https://ollama.com/)                                 | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | `openshell sandbox create --from ollama`로 실행합니다.                         |
| [Pi](https://pi.dev/)                                 | [Community](https://github.com/NVIDIA/OpenShell-Community)                       | `openshell sandbox create --from pi`로 실행합니다.                         |

## 주요 명령어

| 명령어                                                    | 설명                                     |
| ---------------------------------------------------------- | ----------------------------------------------- |
| `openshell sandbox create -- <agent>`                      | 샌드박스를 생성하고 에이전트를 실행합니다.           |
| `openshell sandbox connect [name]`                         | 실행 중인 샌드박스에 SSH로 접속합니다.                     |
| `openshell sandbox list`                                   | 모든 샌드박스를 나열합니다.                             |
| `openshell provider create --type [type] --from-existing`  | 환경 변수로부터 자격 증명 프로바이더를 생성합니다.     |
| `openshell sandbox provider attach <sandbox> <provider>`   | 실행 중인 샌드박스에 프로바이더를 연결합니다.         |
| `openshell policy set <name> --policy file.yaml`           | 실행 중인 샌드박스에 정책을 적용하거나 업데이트합니다.  |
| `openshell policy get <name>`                              | 활성 정책을 표시합니다.                         |
| `openshell logs [name] --tail`                             | 샌드박스 로그를 스트리밍합니다.                            |
| `openshell term`                                           | 디버깅을 위한 실시간 터미널 UI를 실행합니다. |

명령어 가이드, 튜토리얼 및 참조 자료는 [전체 문서](https://docs.nvidia.com/openshell/latest)를 참조하세요.

## 터미널 UI

OpenShell은 [k9s](https://k9scli.io/)에서 영감을 받은, 게이트웨이, 샌드박스 및 프로바이더를 모니터링하기 위한 실시간 터미널 대시보드를 포함합니다.```bash
openshell term

TUI는 게이트웨이와 샌드박스에 대한 실시간 키보드 기반 뷰를 제공합니다. Tab으로 패널을 전환하고, j/k로 목록을 이동하며, Enter로 선택하고, :로 명령 모드에 진입합니다. 게이트웨이 상태와 샌드박스 상태는 2초마다 자동으로 새로고침됩니다.

커뮤니티 샌드박스와 BYOC

--from을 사용하여 OpenShell Community 카탈로그 또는 컨테이너 이미지에서 샌드박스를 생성합니다:```bash openshell sandbox create --from gemini # community catalog docker build -t my-sandbox:latest ./my-sandbox-dir # Docker gateway openshell sandbox create --from my-sandbox:latest # Docker built image podman build -t localhost/my-sandbox:latest ./my-sandbox-dir # Podman gateway openshell sandbox create --from localhost/my-sandbox:latest # Podman built image openshell sandbox create --from registry.io/img:v1 # container image

로컬 게이트웨이에서 사용하는 컨테이너 엔진으로 빌드하세요. 원격
게이트웨이의 경우, 게이트웨이가 풀(pull)할 수 있는 레지스트리에 이미지를 푸시하세요.

자세한 내용은 [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) 카탈로그와 [BYOC 예제](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container)를 참조하세요.

## 에이전트와 함께 OpenShell 사용하기

OpenShell은 사용자와 운영자를 위한 네 가지 이식 가능한 스킬을 제공합니다: CLI 워크플로(`openshell-cli`), 게이트웨이 문제 해결(`debug-openshell-cluster`), 추론 문제 해결(`debug-inference`), 정책 생성(`generate-sandbox-policy`). Agent Skills CLI로 설치하세요:```bash
npx skills add NVIDIA/OpenShell

이러한 공개 설치 가능 스킬은 skills/에 위치하며, 설치된 CLI 도움말과 공개 문서를 진실의 원천으로 사용합니다. OpenShell 소스 체크아웃은 필요하지 않습니다.

에이전트로 구축됨

OpenShell은 자신이 지원하는 것과 동일한 에이전트 주도 워크플로를 사용하여 개발됩니다. 기여자 및 유지관리자 스킬은 .agents/skills/에 별도로 위치합니다. 이들은 OpenShell 저장소에 대한 작업을 자동화하며, 사용자가 공개 스킬을 설치할 때는 포함되지 않습니다:

• 스파이크 및 구축: create-spike로 문제를 조사합니다. 사람이 state:accepted 또는 로드맵 배치로 이를 수락하거나 거절합니다. 수락된 작업은 사람 소유로 남거나, 선택적이고 사람이 게이트하는 agent:* 계획 및 구현 워크플로에 들어갈 수 있습니다.
• 분류 및 라우팅: 커뮤니티 이슈는 triage-issue로 평가됩니다. 에이전트는 기술적 타당성과 영향을 확립하고, 사람은 프로젝트가 조치해야 하는지와 작업이 로드맵에서 어디에 위치하는지를 결정합니다.
• 보안 검토: review-security-issue는 심각도 평가와 교정 계획을 생성합니다. fix-security-issue가 이를 구현합니다.
• 저장소 유지관리: sync-agent-infra, update-docs-from-commits 및 기타 내부 워크플로가 코드, 문서, 에이전트 인프라를 일관되게 유지합니다.

에이전트 구현은 사람이 지시합니다. 사용자가 단계를 직접 요청할 수도 있고, 유지관리자가 선택적 agent:* 워크플로를 사용하여 계획 및 구현을 대기열에 넣고 승인할 수도 있습니다. 전체 워크플로 체인 문서는 AGENTS.md를 참조하세요.

도움 받기

• 질문 및 토론: GitHub Discussions
• 버그 보고: GitHub Issues — 버그 보고 템플릿을 사용하세요
• 보안 취약점: SECURITY.md를 참조하세요 — GitHub Issues를 사용하지 마세요
• 에이전트 지원 도움말: npx skills add NVIDIA/OpenShell로 공개 OpenShell 스킬을 설치하세요

더 알아보기

• 전체 문서 — 개요, 아키텍처, 튜토리얼 및 레퍼런스
• 빠른 시작 — 자세한 설치 및 첫 샌드박스 워크스루
• GitHub 샌드박스 튜토리얼 — 엔드투엔드 범위 지정 GitHub 저장소 접근
• 아키텍처 — 자세한 아키텍처 문서 및 설계 결정
• 로드맵 — 계획된 작업 및 프로젝트 우선순위
• RFC 보드 — rfc 레이블로 OpenShell 로드맵에서 추적되는 RFC 제안
• 지원 매트릭스 — 플랫폼, 버전 및 커널 요구사항
• Brev Launchable — 로컬 설정 없이 클라우드 컴퓨팅에서 OpenShell 사용해 보기
• 에이전트 지침 — 에이전트 기여자를 위한 시스템 프롬프트 및 워크플로 문서

기여

OpenShell은 에이전트 우선으로 구축됩니다. 이슈에는 사용자 스토리, 문제 설명, 영향, 수용 기준이 포함되어야 합니다. 영향은 현재 동작의 결과와 기존 우회 방법이 불충분한 이유를 설명해야 합니다. 기능 요청에는 워크플로 수준의 제안 설계와 대안도 필요하며, 버그 보고에는 재현 단계, 환경 세부 정보, 관련 로그가 추가됩니다. 프로젝트 워크플로 또는 직접 요청을 통해 작업이 승인되면, 기여자는 .agents/skills/의 스킬을 사용하여 현재 코드와 동작을 조사하고, 변경을 구현하고, 검증해야 합니다. 이슈에 이전 진단이 포함되어 있다면, 그것에 의존하지 말고 검증하세요. 전체 에이전트 스킬 표, 기여 워크플로 및 개발 설정은 CONTRIBUTING.md를 참조하세요.

텔레메트리

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

게이트웨이 배포에서 OPENSHELL_TELEMETRY_ENABLED=false를 설정하여 런타임에 텔레메트리를 비활성화하세요. Helm 설치의 경우 server.telemetryEnabled=false를 설정하세요. OpenShell은 이 배포 설정을 샌드박스 슈퍼바이저 환경으로 전파하여 샌드박스 측 텔레메트리 수집도 비활성화됩니다.

텔레메트리를 완전히 컴파일에서 제외할 수도 있습니다. 텔레메트리 지원은 기본 활성화된 telemetry Cargo 기능이며, 이를 포함하는 각 크레이트는 다른 모든 기본 기능을 포함하는 defaults-without-telemetry 별칭도 정의합니다. --no-default-features --features defaults-without-telemetry로 텔레메트리 없는 아티팩트를 빌드하세요:```shell cargo build --release -p openshell-gateway --no-default-features --features defaults-without-telemetry cargo build --release -p openshell-sandbox --no-default-features --features defaults-without-telemetry cargo build --release -p openshell-driver-vm --no-default-features --features defaults-without-telemetry

생성된 바이너리에는 텔레메트리 엔드포인트도, 텔레메트리 HTTP 클라이언트도, 전송 코드도 포함되지 않습니다. 텔레메트리가 컴파일에서 제외되면 게이트웨이는 아무것도 전송하지 않으며, 자신이 실행하는 샌드박스에 텔레메트리가 비활성화되었음을 보고합니다. Cargo는 단일 기본 기능을 제거할 방법이 없으므로, `defaults-without-telemetry`는 반드시 `--no-default-features`와 함께 사용해야 합니다. 단독으로 전달하면 기본 기능이 그대로 남아 빌드가 실패하며, 여전히 전송하는 바이너리가 생성되지 않습니다.

게이트웨이는 또한 내장 컴퓨트 드라이버를 위한 별도의 Cargo 기능들을 노출합니다: `compute-driver-kubernetes`, `compute-driver-docker`, `compute-driver-podman`, `compute-driver-vm`, `compute-driver-mxc`. 기본 기능 집합을 비활성화한 다음, 대상 바이너리에 필요한 드라이버와 텔레메트리 모드만 활성화하십시오. 예를 들어:```shell
# Docker only, with telemetry support.
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-docker

# Docker and VM only, with telemetry compiled out.
cargo build --release -p openshell-gateway --no-default-features --features compute-driver-docker,compute-driver-vm

# Windows MXC only, with telemetry support and bundled Z3.
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-mxc,bundled-z3

일반 빌드는 기본 in-tree-compute-drivers 호환성 기능을 통해 플랫폼 드라이버 세트를 유지합니다. Windows에서는 compute-driver-mxc가 MXC를 선택하며, 나머지 네 가지 기능은 지원되지 않는 드라이버 스텁을 설치합니다. 다른 플랫폼에서는 MXC가 제외됩니다.

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

옵트아웃은 OpenShell이 내보내는 텔레메트리에만 적용됩니다. 사용자가 OpenShell과 함께 구성하고 사용하는 타사 서비스, 모델 프로바이더, 추론 엔드포인트, 에이전트 또는 도구는 자체 약관과 개인정보 처리 방침을 가질 수 있습니다.

당사는 이 텔레메트리에서 집계된 사용 추세를 2주마다 게시합니다. 최신 요약은 커뮤니티 텔레메트리 보고서를 참조하십시오.

고지 및 면책 조항

이 소프트웨어는 외부 자료를 자동으로 검색, 접근 또는 상호 작용합니다. 검색된 자료는 이 소프트웨어와 함께 배포되지 않으며 별도의 약관, 조건 및 라이선스에 의해서만 규율됩니다. 적용 가능한 모든 약관, 조건 및 라이선스를 찾아 검토하고 준수하며, 특정 사용 사례에 대한 검색된 자료의 보안, 무결성 및 적합성을 확인하는 것은 전적으로 사용자의 책임입니다. 이 소프트웨어는 어떠한 종류의 보증도 없이 "있는 그대로" 제공됩니다. 저자는 검색된 자료에 대해 어떠한 진술이나 보증도 하지 않으며, 이 소프트웨어 또는 검색된 자료의 사용 또는 사용 불능으로 인한 손실, 손해, 책임 또는 법적 결과에 대해 어떠한 책임도 지지 않습니다. 이 소프트웨어와 검색된 자료는 사용자 자신의 책임하에 사용하십시오.

라이선스

이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다.