OpenShell 쓰는 법

OpenShell(NVIDIA/OpenShell)는 자율 AI 에이전트 함대를 샌드박스 안에서 돌리라고 만든 오픈소스 런타임이다. 에이전트가 파일·패키지·API·자격 증명을 쓰게 하면서도, 로컬 비밀이나 임의 네트워크로 풀어놓지 않게 YAML 정책(policy)으로 경계를 건다. 라이선스 Apache-2.0. 공식 문서·PyPI 기준 현재 안정 라인은 v0.1.2(OpenShell 0.1.x). 문서는 docs.nvidia.com/openshell.

이 글은 “OpenShell 쓰는 법”만 다룬다. 설치 → 샌드박스 만들기 → 첫 에이전트(공식 Run Your First Agent) → 스킬·SDK·텔레메트리 끄기까지 README와 공식 문서를 따라간다.

핵심 요약 (TL;DR)

• 무엇인가: 모델이 아니다. 에이전트를 커널 수준으로 격리해 돌리는 안전한 프라이빗 런타임이다.
• 설치: curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh 한 줄로 CLI·로컬 게이트웨이를 깐다. 그다음 openshell sandbox create --name demo.
• 첫 에이전트: 프로바이더 프로필 import → 샌드박스 이미지·정책 선택 → --provider와 에이전트 명령으로 create. 문서 예시는 OpenCode + OpenRouter 무료 모델.
• 막히면: 정책이 막은 목적지는 advisor가 규칙을 제안하고, openshell rule approve로 핫리로드.
• 선택: npx skills add NVIDIA/OpenShell, Python uv add openshell, 텔레메트리 OPENSHELL_TELEMETRY_ENABLED=false.

할 수 있는 일

용어를 짧게 푼다. 샌드박스는 에이전트 프로세스가 돌아가는 격리된 실행 경계다. 정책(policy)은 파일시스템·네트워크·프로세스에 대해 “어디까지 허용할지”를 YAML로 적어 둔 규칙이다. 게이트웨이는 샌드박스·정책·접근을 묶는 컨트롤 플레인이다. 에이전트 하네스는 에이전트가 도구·터미널·파일에 손을 대게 해주는 실행 뼈대인데, OpenShell은 그 하네스를 호스트에 풀어놓지 않고 샌드박스+정책 안으로 넣는다.

• 보안 코딩 에이전트: Claude Code, OpenCode, Codex, GitHub Copilot CLI 등을 파일·네트워크 제약이 걸린 채로 돌린다(공식 Overview).
• 프라이빗 엔터프라이즈: 셀프호스트·프라이빗 모델 엔드포인트만 열고, 민감 컨텍스트는 정책으로 지킨다.
• 감사 가능한 통제: 정책 YAML을 버전 관리해 보안 리뷰·감사 대상으로 삼는다.
• 재사용 환경: 기본 Ubuntu 워크로드 또는 직접 만든 컨테이너 런타임을 쓴다.
• 자격 증명 가림: 에이전트는 실제 시크릿을 보지 않고, 승인된 엔드포인트로 가는 요청에만 OpenShell이 붙인다(README).

필요한 것

VRAM·GPU 메모리 숫자는 OpenShell 본체 설치 가이드에 없다. 샌드박스 안 GPU는 Sandboxes 문서 쪽 이야기다. 여기서는 발명하지 않는다.

단계 1: 설치

Quickstart·Installation 문서가 같은 한 줄을 쓴다. Linux / macOS Apple Silicon / Windows WSL2(실험)와 Docker·Podman·호스트 가상화 중 하나가 필요하다.

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

특정 릴리스를 고정하려면 OPENSHELL_VERSION에 태그를 넣는다. 프리릴리스는 OPENSHELL_VERSION=pre, 롤링 개발 빌드는 OPENSHELL_VERSION=dev(Installation 문서).

• macOS: Homebrew로 설치되고 게이트웨이는 Homebrew 서비스. brew services list / brew services restart openshell.
• Linux: Debian/Ubuntu는 deb, Fedora/RHEL은 RPM. 게이트웨이는 systemd 사용자 서비스. 로그아웃 후에도 유지하려면 sudo loginctl enable-linger $USER.
• 0.0.x → 0.1.0: 자리 업그레이드가 안 된다. 옛 런타임을 정리·제거한 뒤 0.1.0을 새로 설치하고, 샌드박스는 전부 다시 만든다(Upgrade guide).

단계 2: 샌드박스 만들기

README Quickstart 그대로다. 기본 이미지는 에이전트가 없는 최소 Ubuntu다.

openshell sandbox create --name demo

실제 에이전트를 돌리려면 이미지가 에이전트 바이너리를 포함해야 하고, 프로바이더를 붙인다. 0.1.x부터 --from은 Dockerfile/디렉터리를 빌드하지 않는다. 먼저 컨테이너 엔진으로 빌드·태그한 뒤 이미지 참조만 넘긴다(Upgrade guide).

단계 3: 첫 에이전트 (공식 워크스루)

문서 Run Your First Agent 흐름을 옮긴다. 예시는 OpenCode를 OpenRouter에 붙인다.

1. 프로바이더 프로필 import

   openshell profile import \
     --url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml
   openshell provider create \
     --name openrouter \
     --type openrouter \
     --from-existing
   

   OPENROUTER_API_KEY를 프로바이더 생성 전에 설정한다. 값은 자격 증명 저장소에 들어가고, openrouter.ai로만 나간다.

2. 샌드박스 이미지 — 예: ghcr.io/anomalyco/opencode:latest (/usr/local/bin/opencode).
3. 샌드박스 생성

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

   문서 예시는 무료 모델이라 OpenRouter 크레딧 없이도 따라갈 수 있다고 적는다.

4. 추가 접근 승인 — 정책에 없는 목적지는 거부되고 advisor가 좁은 규칙을 제안한다.

   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."
   

   승인된 규칙은 재시작 없이 핫리로드된다.

더 긴 예시는 문서의 Run Pi with OpenRouter 튜토리얼을 보면 된다.

단계 4: 스킬 · SDK · 텔레메트리 (선택)

Agent Skills — 코딩 에이전트가 OpenShell CLI·정책·게이트웨이를 다루도록:

npx skills add NVIDIA/OpenShell

SDK — 애플리케이션이 게이트웨이에 붙을 때. CLI를 대신 설치하지 않는다. README 표 기준:

텔레메트리 — README: 운영 카테고리·카운트만 익명으로 모으고, 샌드박스 이름·호스트명·경로·프롬프트·자격 증명·모델명·사용자 콘텐츠는 수집하지 않는다. 끄려면 게이트웨이에 OPENSHELL_TELEMETRY_ENABLED=false, Helm이면 server.telemetryEnabled=false.

막히는 지점 / 왜 막히나

한눈에 비교

실사용자 반응

작성 시점에 GitHub Discussions 인용을 여기에 갖다 붙이지 않는다. 공식 README·Overview가 잡는 포지션만 요약한다. OpenShell은 “에이전트 능력을 줄이지 말고, 파일·네트워크·자격 증명에 대한 명시적 통제를 켠다”는 쪽이다. 위협 표도 같은 결이다 — 데이터 유출·크리덴셜 탈취·미승인 API·권한 상승을 네트워크 정책·Landlock·프로바이더 프로필·seccomp로 막는다. 질문·이슈는 Discussions·Issues, 보안은 SECURITY.md 경로를 따르라고 README가 적는다.

의미와 시사점

검색어 “OpenShell 쓰는 법”은 셸 프롬프트 꾸미기나 일반 Linux shell과 헷갈리기 쉽다. 여기서의 OpenShell은 NVIDIA가 공개한 에이전트 함대용 격리 런타임이다. 모델을 고르는 가이드가 아니라, 이미 쓰는 코딩 에이전트를 정책이 걸린 샌드박스에 넣는 방법이다. TWMS 독자 기준으로는 Orca(병렬 ADE)·security-audit-skill(감사 스킬)과 결이 다르다. “에이전트를 더 많이”가 아니라 “에이전트가 만져도 되는 범위를 코드로 고정”하는 쪽에 가깝다. 0.1.x로 넘어가며 자리 업그레이드가 끊긴 점도, 프로덕션에 올릴 때 릴리스 노트를 먼저 읽으라는 신호다.

마치며

OpenShell 쓰는 법은 공식 문서가 이미 짧게 적어 두었다. install.sh로 CLI와 게이트웨이를 올리고(v0.1.2 문서 채널), openshell sandbox create로 경계를 만든 뒤 Run Your First Agent대로 프로바이더와 이미지를 붙인다. 막히면 rule approve로 좁게 연다. VRAM 같은 숫자는 문서에 없으니 추정하지 말고, Support Matrix와 정책 문서를 보면 된다. 오늘은 그 루프만 복사하면 된다.

출처

• GitHub — NVIDIA/OpenShell
• NVIDIA OpenShell Docs — Overview
• Installation · Run Your First Agent
• Support Matrix · Upgrade to 0.1.0
• PyPI — openshell

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.