How nvidia/openshell works
OpenShell is a governed runtime for autonomous agents: users create and manage sandboxes through the CLI or SDK, while the gateway coordinates control-plane operations and the supervisor and sandbox enforce runtime boundaries. Policies declare allowed file, process, and network access; policy changes can be formally checked before approval. The README also documents provider credentials, extensibility, and multiple compute drivers. Source excerpts are limited, so dashed, uncited links mark relationships whose implementation wiring was not shown.
Main entry points: service.rs Gateway server · src/main.rs Supervisor · src/main.rs Sandbox process · lib.rs Policy enforcement
Components 21
User interfaces
- OpenShell CLI
crates/openshell-cli/src/main.rs - Rust SDK
crates/openshell-sdk/src/client.rs
Gateway control plane
- Gateway server
crates/openshell-server/src/grpc/service.rs - Sandbox RPCs
crates/openshell-server/src/grpc/sandbox.rs - Workspace RPCs
crates/openshell-server/src/grpc/workspace.rs - Durable state
crates/openshell-server/src/persistence/postgres.rs - Service endpoint routing
crates/openshell-server/src/service_routing.rs
Sandbox runtime
- Supervisor
crates/openshell-supervisor/src/main.rs - Sandbox process
crates/openshell-sandbox/src/main.rs - Sandbox backend
crates/openshell-sandbox-backend/src/runtime.rs
Policy and access
- Policy enforcement
crates/openshell-policy/src/lib.rs - Kernel confinement
crates/openshell-sandbox/src/linux/seccomp_notify.rs - Policy prover
crates/openshell-prover/src/lib.rs - Provider credentials
crates/openshell-providers/src/profiles.rs - Network mediation
crates/openshell-supervisor-network/src/opa.rs
Drivers and extensions
- Docker driver
crates/openshell-driver-docker/src/lib.rs - Podman driver
crates/openshell-driver-podman/src/driver.rs - Kubernetes driver
crates/openshell-driver-kubernetes/src/driver.rs - VM driver
crates/openshell-driver-vm/src/driver.rs - Middleware and interceptors
crates/openshell-gateway-interceptors/src/routes.rs
Other components
- Operator or agent developer
Connections 22
- Operator or agent developer → OpenShell CLI: manages sandboxes
README.md - Operator or agent developer → Rust SDK: uses gateway API
README.md - OpenShell CLI → Gateway server: issues operations
- Rust SDK → Gateway server: calls gRPC API
crates/openshell-sdk/src/client.rs - Gateway server → Sandbox RPCs: routes sandbox RPCs
crates/openshell-server/src/grpc/service.rs - Gateway server → Workspace RPCs: routes workspace RPCs
crates/openshell-server/src/grpc/service.rs - Sandbox RPCs → Durable state: reads and writes
- Workspace RPCs → Durable state: reads and writes
- Gateway server → Service endpoint routing: routes endpoint traffic
crates/openshell-server/src/service_routing.rs - Gateway server → Supervisor: coordinates runtime
- Supervisor → Sandbox process: launches workload
- Sandbox process → Sandbox backend: uses runtime backend
- Sandbox process → Kernel confinement: confines system access
README.md - Policy enforcement → Sandbox process: governs workload access
README.md - Policy prover → Policy enforcement: checks proposed changes
README.md - Network mediation → Policy enforcement: checks network access
README.md - Provider credentials → Network mediation: supplies scoped credentials
README.md - Supervisor → Docker driver: selects compute driver
- Supervisor → Podman driver: selects compute driver
- Supervisor → Kubernetes driver: selects compute driver
- Supervisor → VM driver: selects compute driver
- Gateway server → Middleware and interceptors: supports extension hooks
README.md