OpenShell 딥다이브
— AI에게 일을 맡기되, 권한은 경계 안에

1프로젝트 한줄 요약

OpenShell은 자율 AI 에이전트를 위한 정책 기반 실행 환경입니다. 에이전트 프로그램을 샌드박스 안에서 실행하고, 허용된 파일과 외부 서비스만 사용하도록 경계를 세웁니다. 모델을 학습시키는 라이브러리나 대화를 만드는 프레임워크와는 역할이 다릅니다.

이 저장소의 핵심은 에이전트가 잘 판단한다고 가정하지 않고, 실행 환경이 권한을 제한하도록 만드는 것입니다. 에이전트가 실수하거나 외부 문서의 악성 지시를 따라도, 그 행동이 통과해야 하는 별도의 통제 지점을 둡니다.

1-1. 세 구성 요소만 먼저 기억하기

사용자는 CLI나 SDK로 gateway에 요청합니다. compute driver가 실행 자원을 준비하고, supervisor가 경계를 확인한 뒤 에이전트를 시작합니다. 모델 API를 이용한다면 승인된 요청은 외부 모델 서비스까지 나갑니다. 제품 설명의 “private”를 모든 추론과 데이터가 자동으로 내 컴퓨터에만 남는다는 뜻으로 읽으면 안 됩니다.

2왜 주목받는가

선정 근거는 TrendShift Daily #14이며 분석일은 2026-10-23입니다. 2026-10-23 GitHub 기준 스타 18,034개, 포크 1,843개입니다. 이 숫자는 관심의 규모를 보여주지만, 하루 증가량이나 채택 기업 수, 실제 운영 안정성을 뜻하지는 않습니다.

2-1. 주목할 만한 세 가지 변화

1. 도구 호출이 실제 권한 문제가 됐습니다. 파일 수정과 네트워크 호출을 하는 에이전트에는 파일 경계·목적지 제한·비밀키 관리가 함께 필요합니다. OpenShell은 이들을 하나의 제품 흐름에 연결합니다.
2. 거절 다음 단계까지 설계합니다. 정책 advisor가 필요한 접근을 제안하고, prover가 기존 정책 대비 새 위험을 검사하는 경로가 있습니다. 단순한 허용 목록을 사람이 처음부터 완벽히 작성해야 하는 부담을 줄이려는 접근입니다.
3. 로컬과 클러스터를 같은 계약으로 묶습니다. Docker·Podman·Kubernetes·VM 드라이버가 있고, HEAD는 Kubernetes의 공유 supervisor 배치를 추가합니다. 보안 경계와 자원 배치를 나누는 사례입니다.

위 항목은 README와 실제 구현을 바탕으로 한 관심 요인에 대한 해석입니다. 트렌딩 순위만으로 특정 발표나 기능이 관심 증가의 원인이라고 단정할 수는 없습니다. 2026-10-23 GitHub 기준 최신 릴리스는 v0.1.5(2026-10-20)이며, 분석 소스는 그 뒤의 개발 커밋입니다.

2-2. 경쟁·대체 접근과 비교하면 무엇이 다른가

gVisor와 Firecracker의 역할 설명은 각각 gVisor 공식 개요와 Firecracker 공식 문서를 확인했습니다. 이 표는 역할과 구현 범위 비교이며 처리량·부팅 시간·격리 강도의 실측 순위가 아닙니다. Docker 관련 비교는 이 저장소의 Docker 드라이버가 추가하는 통제 기능을 기준으로 했습니다.

OpenShell의 장점은 격리 기술 하나의 발명보다, 실행 경계·권한 정책·자격증명·운영 API를 연결한 설계에 있습니다.

3기술 스택 전체 지도

루트 Cargo.toml은 members = ["crates/*"]인 Rust workspace입니다. edition은 2024, 최소 Rust 버전 선언은 1.94입니다. 반면 rust-toolchain.toml과 mise.toml이 선택한 개발 도구는 1.95.0입니다. 최소 지원 버전과 팀이 사용하는 컴파일러는 서로 다른 정보입니다.

3-1. 백엔드: 비동기 통신과 정책 엔진

공통 버전의 근거는 Cargo.toml과 Cargo.lock입니다. Regorus 선언은 crates/openshell-supervisor-network/Cargo.toml에 있습니다. 공통 설정에는 k8s-openapi = "0.24"의 v1_29 기능과 opentelemetry = "0.32", metrics = "0.24"도 포함됩니다.

3-2. 프론트엔드·클라이언트: 브라우저 화면보다 터미널과 SDK

주요 사용자 접점은 CLI와 TUI입니다. CLI에는 clap = "4.5", TUI에는 ratatui = "0.30.2"와 crossterm = "0.28"을 선언합니다. crates/openshell-tui/src/lib.rs의 run()은 터미널 raw mode와 alternate screen을 열고 gRPC 클라이언트를 화면 상태에 연결합니다.

sdk/typescript/src/client.ts는 생성된 protobuf 타입 위에 SandboxClient 같은 사용하기 쉬운 API를 얹습니다. sdk/typescript/src/transport.ts는 연결·인증, sdk/typescript/src/errors.ts는 오류 분류를 맡습니다. ./raw export는 저수준 접근을 위한 별도 진입점입니다.

fern/와 docs/의 TSX·MDX는 문서 사이트 구성입니다. fern/docs.yml에는 테마·메뉴·문서 버전 설정이 있습니다. TypeScript와 TSX가 보인다는 이유만으로 React 기반 제품 대시보드가 있다고 소개해서는 안 됩니다.

3-3. 인프라·빌드: 실행 파일을 먼저 만들고 이미지에 넣기

• mise.toml: Python 3.14.5, Rust 1.95.0, Node 24.15.0, Go 1.26.7, uv 0.10.12, protoc 29.6, Helm 4.2.0을 고정합니다. 이는 개발 도구 조합입니다.
• deploy/docker/Dockerfile.sandbox: FROM scratch에서 미리 빌드한 정적 musl 바이너리만 복사하고, USER 65532:65532로 설정합니다. 기본 에이전트 이미지와 별개의 신뢰 런타임 이미지입니다.
• deploy/docker/Dockerfile.gateway: distroless Debian 13의 nonroot 이미지를 사용하고, USER 1000:1000, 기본 포트 8080을 지정합니다.
• deploy/docker/Dockerfile.supervisor: base-nossl-debian13에 GNU 바이너리를 넣습니다. 실제 실행 UID는 driver 배치 설정도 함께 봐야 합니다.
• deploy/helm/openshell/values.yaml: 기본 gateway 복제본은 1, workload 종류는 statefulset입니다. 다중 복제본에는 외부 DB 설정이 필요합니다.

gateway·supervisor Dockerfile의 기본 베이스 이미지에는 digest가 고정되어 있습니다. deploy/helm/openshell/Chart.yaml의 version과 appVersion은 0.0.0이며 주석상 CI가 릴리스 버전으로 바꿉니다. Rust workspace·TypeScript 패키지의 0.0.0도 2026-10-23 GitHub 기준 최신 릴리스 v0.1.5와 혼동하지 않아야 합니다.

3-4. CI에서 보는 제품의 품질 기준

.github/workflows/branch-checks.yml은 protobuf 호환성 검사, cargo fmt, cargo clippy --locked --workspace --all-targets -- -D warnings, cargo nextest, PostgreSQL 테스트, Python·Go·TypeScript 검사를 나눕니다. --locked는 CI에서 의존성 해석이 예기치 않게 바뀌지 않도록 합니다. 검사 항목의 정의와 개별 CI 실행의 성공 여부는 별개입니다.

기술 스택을 읽을 때는 언어 이름보다, 각 의존성이 어느 신뢰 경계와 사용자 접점을 담당하는지 연결하는 것이 중요합니다.

4아키텍처 심화 분석

4-1. 전체 흐름: 관리 요청과 실제 작업 트래픽

아래 그림의 위쪽은 관리 흐름, 아래쪽은 에이전트의 작업 흐름입니다. gateway가 정책을 관리한다고 해서 모든 외부 API 트래픽을 gateway가 직접 프록시한다는 뜻은 아닙니다. 허용된 upstream 연결을 여는 책임은 supervisor에 있습니다.

Docker·Podman은 driver 소유 볼륨의 Unix socket, Kubernetes는 사설 TCP 경로와 mTLS, VM은 vsock를 사용합니다. 논리적으로 같은 Sandbox Protocol을 서로 다른 전송 방식을 사용하는 구조입니다. HTTP/2의 독립 스트림은 하나의 느린 전송 때문에 DNS나 프로세스 제어까지 대기하는 일을 줄이도록 설계되어 있습니다. 이는 docs/about/architecture.mdx가 설명하는 계약이며 성능 수치를 측정한 결과는 아닙니다.

4-2. 패턴 ① 권한 분리와 교체 가능한 실행 백엔드

핵심 질문: 신뢰할 수 없는 프로그램과 비밀키·정책 결정을 같은 곳에 둘 필요가 있을까요? 이 설계는 sandbox를 작업 경계 안에 두고 supervisor를 그 밖에 둡니다. sandbox는 요청 주체를 관찰하고 전달하지만 외부 서비스 접근을 최종 승인하지 않습니다.

crates/openshell-server/src/compute/mod.rs의 SharedComputeDriver는 다음처럼 공통 계약 뒤에 실제 드라이버를 감춥니다.

// 원본의 타입 별칭. 여러 구현을 공통 인터페이스로 다룹니다.
pub type SharedComputeDriver =
    Arc<dyn ComputeDriver<WatchSandboxesStream = DriverWatchStream> + Send + Sync>;

Arc는 여러 비동기 작업이 드라이버를 공동 소유하게 하고, dyn ComputeDriver는 Docker인지 Kubernetes인지 몰라도 같은 API를 호출하게 합니다. Send + Sync는 스레드를 넘나들며 사용할 수 있는 자료형인지 컴파일러가 확인할 조건입니다. 초보자는 우선 “공통 리모컨에 여러 제조사의 장치를 연결한다”는 정도로 이해해도 됩니다.

드라이버의 책임은 추상화만으로 끝나지 않습니다. Docker의 crates/openshell-driver-docker/src/lib.rs에는 validate_docker_outer_fence()가 있고 workload 생성 설정에 network_mode: Some("none".to_string())을 넣습니다. crates/openshell-driver-docker/src/isolation.rs의 DockerOuterFenceEvidence::project()는 컨테이너 ID, 네트워크 모드, 예상 밖 네트워크를 확인해 세대에 묶인 경계 증거를 만듭니다.

4-3. 패턴 ② 커널 중개와 실패 시 차단

핵심 질문: 에이전트가 프록시 환경변수를 무시하고 직접 소켓을 열면 어떻게 될까요? Linux 구현은 자식에게 상속되는 seccomp 필터와 driver의 네트워크 울타리를 결합합니다. 프록시를 잘 사용해 주리라는 약속에만 기대지 않습니다.

1. crates/openshell-sandbox/src/linux/workload_launcher.rs의 start()가 전용 launch 스레드를 만들고 install_workload_listener()를 설치합니다. 작업 큐는 sync_channel(64)입니다.
2. WorkloadLauncher::execute()로 fork/exec 작업을 그 스레드에 모읍니다. 자식은 필터를 상속하지만 sandbox의 중개·생명주기 스레드는 같은 필터에 묶이지 않습니다.
3. crates/openshell-sandbox/src/linux/seccomp_notify.rs의 install_workload_listener()가 socket, connect, setsockopt 등 정해진 호출을 다룹니다. crates/openshell-sandbox/src/network_broker.rs의 dispatch_notification(), connect_socket()을 따라가면 중개 경로가 보입니다.
4. probe_notification_api()는 실제 user notification 왕복과 SECCOMP_ADDFD_FLAG_SEND 동작을 검사합니다. 커널 버전 문자열만 보고 필요한 기능이 있다고 가정하지 않습니다.

파일 경계는 crates/openshell-sandbox/src/sandbox/linux/landlock.rs에서 봅니다. require_abi()는 최소 ABI 3을 요구하고, prepare_capability_free_baseline()은 비공개 /.openshell 계층을 제외하는 필수 기본 규칙을 만듭니다.

// 필수 기본 규칙 생성 과정에서 발췌
require_abi()?;
let abi = ABI::V3;
let access = AccessFs::from_all(abi);
let mut ruleset = Ruleset::default()
    .set_compatibility(CompatLevel::HardRequirement)
    .handle_access(access)

위 코드는 이어지는 규칙 생성 중 앞부분입니다. ?는 오류가 나면 호출자에게 전파한다는 Rust 문법입니다. “기능이 없으면 조용히 제한을 생략”하는 방향으로 흐르지 않도록 합니다. 선택적 파일 정책의 best_effort 설정도 이 필수 기본 경계를 해제하지 않습니다.

4-4. 패턴 ③ 요청별 승인과 자격증명 결합

핵심 질문: 인터넷 접속을 허용했다는 이유만으로 그곳에 API 키도 보낼 수 있어야 할까요? 소스는 네트워크 허용과 자격증명의 목적지 결합을 나누어 검사합니다.

crates/openshell-supervisor-network/src/opa.rs의 authorize_egress()는 현재 정책 세대와 함께 egress_authorization을 평가합니다. crates/openshell-supervisor-network/data/sandbox-policy.rego는 기본값을 default allow_network = false로 둡니다. 허용 규칙에는 endpoint와 binary 조건이 함께 등장합니다.

# 네트워크 정책의 핵심 규칙 발췌
network_policy_for_request if {
    some name
    data.network_policies[name]
    endpoint_allowed(data.network_policies[name], input.network)
    binary_allowed(data.network_policies[name], input.exec)
}

여기서 binary는 에이전트가 말로 신고한 이름이 아닙니다. crates/openshell-binary-identity/src/lib.rs의 ProcfsIdentityResolver가 신뢰할 수 있는 procfs 관찰을 공유합니다. 심볼릭 링크로 실행한 Python의 실제 경로가 정책에 적은 경로와 달라 거절될 수 있다는 점도 Rego의 거절 진단문에 명시되어 있습니다.

crates/openshell-supervisor-network/src/l7/relay.rs의 scoped_context_for_request()는 resolver_and_body_classifier_for_endpoint()로 host·port·path에 맞는 resolver를 고릅니다. 요청 authority가 없을 때는 static credential resolver를 지우는 분기도 있습니다. prepare_inspected_request()는 동적 grant를 다루고, 대기 중 정책·credential 세대가 바뀌었는지도 확인합니다.

L7 검사는 설정한 프로토콜과 강제 모드의 범위에서 적용됩니다. 단순 L4 TCP 허용은 “그 연결 안의 모든 API 동작이 안전하다”는 뜻이 아닙니다. TLS 내용을 검사하는 경로에서는 supervisor가 TLS를 종단하고 검사하므로, 클라이언트의 인증서 신뢰 설정과 프로토콜 호환성도 운영 고려 사항이 됩니다.

4-5. 패턴 ④ 버전이 있는 상태 변경과 제한된 정책 증명

핵심 질문: 내가 검토한 상태와 실제 적용할 상태가 그사이 달라지면 어떻게 할까요? 최신 Kubernetes 변경과 정책 제안 처리에서 이 문제를 서로 다른 수준으로 다룹니다.

crates/openshell-driver-kubernetes/src/shared_supervisor.rs의 supervisor_placement()는 시작 세대에 기록된 annotation을 읽습니다. 기록이 없으면 Dedicated, gateway와 유효한 route가 있으면 Shared { route }를 반환합니다. 모르는 값이나 불완전한 기록은 오류입니다. 전역 설정을 바꿨다고 기존 세대의 배치를 다르게 해석하지 않게 합니다.

crates/openshell-supervisor-control/src/controller.rs의 replace_assignments()는 목록을 읽었던 baseline과 현재 revision을 비교합니다.

// replace_assignments()의 초기화 이후 충돌 검사 발췌
if desired.initialized && desired.revision != baseline {
    return Err(AssignmentError::Conflict {
        baseline,
        current: desired.revision,
    });
}

그사이 누군가 배정을 바꿨다면 오래된 전체 목록으로 덮어쓰지 않습니다. 같은 파일의 MAX_ASSIGNED_INSTANCES = 256은 공유 host의 구현상 상한입니다. 이는 장비당 권장 동시 실행 수나 성능 보장이 아닙니다.

정책 쪽은 crates/openshell-server/src/grpc/policy.rs의 evaluate_proposal_candidate(), proposal_prover_result(), run_prover_findings()를 읽습니다. 현재 유효 정책과 후보 정책에서 각각 발견 항목을 구한 뒤 finding_delta()로 새 위험을 가려냅니다.

crates/openshell-prover/src/containment.rs의 check_within_boundary()는 별도의 질문, 즉 후보 정책이 상위 경계를 넘는지 검사합니다. 네트워크에서는 개념적으로 후보가 허용함 ∧ 경계가 거절함인 행동을 찾습니다. 그런 반례가 있으면 포함 관계가 깨집니다. 지원하지 않는 형태와 시간 초과도 결과로 구분합니다.

보안 설계는 정상 요청의 허용 조건뿐 아니라, 오래된 상태·모르는 입력·검사 불능을 처리하는 방식에서 드러납니다.

5디렉토리 구조 해부

아래는 저장소 루트 기준의 축약 트리입니다. crates/는 제품 구현, proto/는 통신 계약을 담으며, 다른 폴더는 클라이언트·배포·검증을 지원합니다.

5-1. 비슷한 이름의 폴더가 나뉜 이유

예를 들어 crates/openshell-policy-schema/src/yaml.rs는 DuplicateKeyPolicy::Error를 지정하고 객체 위치의 null을 검사합니다. 이런 규칙은 CLI·서버·prover가 제각각 YAML을 해석하는 문제를 줄입니다. “설정 파일도 외부 입력”이라는 관점을 배우기 좋은 진입점입니다.

5-2. 처음 읽을 때의 추천 경로

1. docs/about/architecture.mdx로 구성 요소 이름과 신뢰 경계를 익힙니다.
2. proto/sandbox.proto와 crates/openshell-policy-schema/src/lib.rs로 데이터 모양을 봅니다.
3. crates/openshell-supervisor-network/src/opa.rs와 crates/openshell-supervisor-network/data/sandbox-policy.rego에서 허용 판단을 찾습니다.
4. crates/openshell-sandbox/src/linux/workload_launcher.rs와 crates/openshell-sandbox/src/network_broker.rs로 요청이 중개되는 이유를 확인합니다.
5. crates/openshell-server/src/grpc/policy.rs와 crates/openshell-supervisor-control/src/controller.rs에서 변경·충돌 처리를 읽습니다.

제품 구현 파일은 crates/ 아래에 있으며, 경로는 모두 저장소 루트 기준입니다. 파일이 크면 처음부터 끝까지 읽기보다 함수명 검색 → 호출자 → 관련 테스트 순으로 이동하세요. 테스트는 함수가 약속하는 실패 조건을 설명하는 또 하나의 문서입니다.

6학습 포인트 (기술별)

6-1. Rust: 소유권을 “누가 책임지는가”로 읽기

Arc는 공유 소유, Mutex는 동시 변경 제한, Result는 실패를 반환값으로 드러내는 장치입니다. crates/openshell-supervisor-control/src/controller.rs에서 이 세 요소가 배정 목록을 지키는 방식을 보세요. 문법을 외우기 전에 “어떤 상태를 누가 바꿀 수 있나”를 메모하면 구조가 보입니다.

실습 아이디어: assign()와 unassign()에서 잠금 획득, 상태 변경, revision 증가, watch 알림을 서로 다른 색으로 표시해 보세요. 동일한 값의 재배정과 실제 변경이 어떻게 구분되는지 설명하면 됩니다.

6-2. 비동기·동시성: 채널은 작업 큐와 상태 알림이 다르다

WorkloadLauncher의 sync_channel은 실행할 작업을 전달합니다. controller의 Tokio watch는 revision 같은 최신 상태 변경을 알립니다. 같은 “채널”이어도 모든 작업을 처리할 큐와 최신 상태를 따라잡을 알림은 요구사항이 다릅니다.

실습 아이디어: 네트워크가 느려진 상황에서 작업 큐, HTTP/2 스트림, host 상태 알림이 각각 어떤 자원을 보호하는지 표로 적어 보세요. 제한값을 키우기 전에 메모리·파일 디스크립터·대기 시간 중 무엇이 증가하는지 생각합니다.

6-3. gRPC·SDK: 전송 자료형과 사용자 API를 나누기

proto/sandbox.proto는 SandboxPolicy에 filesystem, process, network 정책을 넣는 계약을 정의합니다. 필드 번호는 wire 호환성의 일부입니다. 이름이 같아 보여도 번호를 임의 재사용하면 이전 데이터 해석이 달라질 수 있습니다.

// proto/sandbox.proto의 SandboxPolicy 필드 발췌
uint32 version = 1;
FilesystemPolicy filesystem = 2;
LandlockPolicy landlock = 3;
ProcessPolicy process = 4;
map<string, NetworkPolicyRule> network_policies = 5;

실습 아이디어: TypeScript의 durationFromSeconds()가 음수·무한대 입력을 왜 거절하는지 살펴보고, SDK의 친숙한 초 단위 값이 protobuf duration으로 바뀌는 과정을 적어 보세요. 자동 생성 코드와 사용성 개선 코드를 나누는 이유를 배울 수 있습니다.

6-4. 정책 언어: 설정도 작은 프로그래밍 언어다

아래는 공식 네트워크 정책 튜토리얼의 규칙에 버전·파일 영역을 붙인 학습용 예시입니다. 정책 구조를 설명하는 예시이며, 실제 실행에는 적절한 workload 이미지와 실행 환경이 필요합니다.

version: 1
filesystem_policy:
  include_workdir: true
  read_only: [/usr, /etc]
  read_write: [/tmp]
network_policies:
  github_api:
    endpoints:
      - host: api.github.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/bin/curl

read-only는 이 REST 설정에서 GET, HEAD, OPTIONS를 허용하는 접근 프리셋입니다. 애플리케이션이 GET에 부작용을 구현했다면 그 의미까지 바꿔 주지는 않습니다. 실습 아이디어: host·binary·메서드 중 하나만 바꾼 요청을 만들고 어떤 검사에서 거절할지 적으세요.

6-5. 운영체제 보안: 다층 통제의 담당 범위

Landlock은 파일 접근, seccomp는 지정 시스템 호출의 통제·중개, 바깥 네트워크 울타리는 직접 유출 경로, supervisor는 목적지와 요청 의미를 다룹니다. crates/openshell-sandbox/src/linux/socket_confinement.rs의 confine_to_loopback()과 probe_loopback_confinement()도 함께 읽어 보세요.

실습 아이디어: “파일 읽기”, “DNS 질의”, “TCP 연결”, “허용 API에 POST”라는 네 행동을 어느 구성 요소가 관찰·차단하는지 배치하세요. 모든 통제를 막연히 Docker 한 단어로 묶지 않는 연습입니다.

6-6. 관측성·증명: 판단을 설명 가능한 자료로 남기기

openshell-ocsf는 보안 사건을 구조화하고, openshell-otel은 서비스 경계의 trace를 연결합니다. crates/openshell-server/src/compute/mod.rs의 TracedDriver::call()은 드라이버 호출을 span에 넣고 gRPC 결과를 기록합니다. 보안 거절과 내부 연결 오류를 다른 종류의 사건으로 볼 수 있습니다.

실습 아이디어: 같은 실패를 사용자 메시지, 운영 trace, 보안 이벤트로 각각 표현해 보세요. 운영자가 원인을 찾는 데 필요한 필드와 비밀값이 섞이면 안 되는 필드를 나누는 것이 목표입니다.

배울 것은 라이브러리 목록이 아니라, 권한·동시성·오류·관측성을 하나의 요청 흐름에 묶는 방법입니다.

7하드웨어 / 시스템 요구사항

요구사항의 1차 근거는 이 커밋의 docs/about/support-matrix.mdx입니다. 코드만 읽는 학습에는 Docker·Kubernetes·GPU가 필요하지 않습니다. 실행을 준비한다면 아래의 지원 조건과 선택한 드라이버를 먼저 확인해야 합니다.

7-1. 커널은 버전보다 기능 검사가 중요하다

• Landlock ABI 3 이상: upstream Linux 6.2에서 도입된 기능이며 LSM이 활성화되어야 합니다.
• seccomp user notification: 중첩 필터와 원자적인 FD 주입·응답 기능을 기존 런타임 보안 프로필 아래에서 사용할 수 있어야 합니다.
• 작업 메모리 읽기: non-dumpable broker가 같은 UID의 dumpable 자식 메모리를 process_vm_readv 또는 /proc/<pid>/mem으로 읽을 수 있어야 합니다.
• 소켓 제한: 추가 Linux capability 없이 SO_BINDTODEVICE로 workload 소켓을 loopback에 결합할 수 있어야 합니다.

배포판 backport와 보안 프로필 때문에 “Linux 6.2 이상” 한 줄만으로 지원 여부가 확정되지 않습니다. 소스의 probe는 실제 부모·자식 실행 형태에서 필요한 연산을 확인합니다. cap_drop: ALL과 no-new-privileges:true도 Docker workload 생성 코드에서 확인됩니다.

7-2. CPU·메모리·GPU는 어느 정도인가

deploy/helm/openshell/values.yaml의 gateway 자원 기본값은 resources: {}입니다. 이것을 “메모리를 거의 안 쓴다”로 해석할 수는 없습니다. 에이전트 이미지, 빌드 작업, 브라우저, 동시 실행 수가 실제 자원 사용량을 좌우합니다.

8직접 해볼 수 있는 실습 과제

아래 과제는 저장소 수정·설치·서비스 실행 없이 할 수 있는 소스 읽기 중심 실습입니다. 명령 예시는 저장소 루트에서 파일을 읽고 검색하는 용도입니다. YAML·요청 예시는 사고 실험이며, 외부 API로 보내지 않습니다.

# 파일을 나열하고 문서와 함수 위치만 읽습니다.
rg --files crates/openshell-cli/src crates/openshell-server/src
rg --files crates/openshell-supervisor/src crates/openshell-sandbox/src
rg -n 'authorize_egress|prepare_inspected_request' crates/openshell-supervisor-network/src
rg -n 'message SandboxPolicy' proto/sandbox.proto

# 의도적으로 중복 키를 넣은 잘못된 학습용 입력
version: 1
network_policies: {}
network_policies:
  unexpected_rule:
    endpoints: []

# boundary.yaml: 최대 허용 범위
version: 1
filesystem_policy:
  read_only: [/usr, /etc]

# candidate.yaml: 이 범위 안에 있는지 확인할 정책
version: 1
filesystem_policy:
  read_only: [/usr]
  read_write: [/tmp]

9관련 기술 심화 학습 로드맵

주당 3~5시간의 읽기와 정리를 가정한 제안입니다. Rust가 처음이면 1주차를 더 길게 잡아도 좋습니다. 매주 “내가 그린 설명이 어떤 소스와 연결되는가”를 남기는 것이 목표입니다.

모든 단계를 구현하려고 서두르기보다 각 주의 산출물을 다른 사람에게 설명해 보세요. 이해가 막히면 용어를 더 찾기 전에 입력·출력·실패 세 가지만 다시 적으면 됩니다. 독립 실행 실험은 지원 환경과 버전 준비를 마친 뒤 별도의 학습 단계로 진행할 수 있습니다.

한 요청의 입력·권한 판단·실제 I/O·실패 기록을 끝까지 따라갈 수 있으면, 큰 저장소도 학습 가능한 크기로 나눌 수 있습니다.

10핵심 키워드 사전

비슷한 이름이 가장 위험한 혼동을 만듭니다. sandbox와 supervisor, 정책 형식의 version과 실행 상태의 revision, Rust crate 버전과 Linux ABI 버전은 각각 다른 의미입니다. 메모할 때 “무엇의 버전인가”까지 함께 적으세요.

11참고 링크

11-1. 프로젝트와 주요 소스

• 공식 저장소 NVIDIA/OpenShell · README, 이슈, 릴리스의 출발점
• 분석 커밋 9a85667의 전체 트리 · 본문 파일 경로의 기준
• v0.1.5 릴리스 · 2026-10-23 GitHub 기준 최신 릴리스
• 공식 최신 문서 · 배포·운영 전 선택한 버전과 대조
• 분석 커밋의 아키텍처 문서 · 경계·인증·전송 계약
• 분석 커밋의 지원 표 · 플랫폼·커널·런타임 조건
• Cargo.toml · Cargo.lock · 선언 범위와 잠금 버전
• workload_launcher.rs · 자식에게 상속시키는 필터와 전용 실행 스레드
• Landlock 구현 · 필수 ABI와 기본 보호 경계
• opa.rs · l7/relay.rs · 정책 평가와 요청별 자격증명 처리
• 정책 제안·검증 처리 · boundary 포함 검사
• Kubernetes supervisor 배치 · 공유 host controller

11-2. 관련 기술을 더 공부할 공식 문서

• Rust 공식 입문서 · 소유권, trait, 오류 처리
• Tokio 튜토리얼 · 비동기 작업과 채널
• gRPC 개요 · 원격 호출과 스트리밍
• Protocol Buffers 언어 가이드 · 필드 번호와 계약 변경
• Linux Landlock 문서 · seccomp 문서
• Rego 정책 언어 · Z3 가이드
• Kubernetes NetworkPolicy · 네트워크 격리 모델
• gVisor 공식 개요 · Firecracker 공식 개요 · 2장의 비교 자료

11-3. 현재 상태 (2026-10-23 확인)

GitHub 수치는 2026-10-23 GitHub API 기준입니다. 구현·버전·코드 규모의 기준 커밋은 9a85667입니다. 릴리스와 개발 커밋의 구현에는 차이가 있을 수 있습니다.

11-4. 언어별 코드 규모

집계는 git ls-files -z로 얻은 추적 파일 중 일반 파일을 대상으로 확장자별 개행 수를 더한 것입니다. 빈 줄·주석·테스트·예제·추적된 생성 코드를 포함하며 .git, 빌드 산출물, 외부 의존성 원본은 포함하지 않습니다. 따라서 “직접 작성한 제품 로직의 양”이나 프로젝트 간 생산성 지표로 사용하면 안 됩니다.

특히 Go에는 *.pb.go 5개, 29,508줄의 생성 코드가 포함됩니다. crates/ 아래 Rust는 609,616줄이고 나머지 Rust 집계에는 e2e·예제·테스트 등이 들어갑니다. 파일별 AST를 해석하는 도구로 실행문만 센 수치가 아닙니다.

수치와 기능 설명에 기준 날짜·커밋·집계 방법을 함께 남겨야, 빠르게 바뀌는 저장소도 다시 확인하며 공부할 수 있습니다.