# nvidia/openshell architecture

> Architecture diagram of the GitHub repository nvidia/openshell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/openshell
- Repository: https://github.com/nvidia/openshell
- Video tour (about a minute): https://gitdiagram.com/nvidia/openshell/video

## Overview

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: [`crates/openshell-server/src/grpc/service.rs`](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/service.rs) (Gateway server), [`crates/openshell-supervisor/src/main.rs`](https://github.com/nvidia/openshell/blob/main/crates/openshell-supervisor/src/main.rs) (Supervisor), [`crates/openshell-sandbox/src/main.rs`](https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox/src/main.rs) (Sandbox process), [`crates/openshell-policy/src/lib.rs`](https://github.com/nvidia/openshell/blob/main/crates/openshell-policy/src/lib.rs) (Policy enforcement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["OpenShell CLI<br/>[main.rs]"]
  node_sdk["Rust SDK<br/>[client.rs]"]
end

subgraph group_control["Gateway control plane"]
  node_gateway["Gateway server<br/>[service.rs]"]
  node_grpc_sandbox["Sandbox RPCs<br/>[sandbox.rs]"]
  node_grpc_workspace["Workspace RPCs<br/>[workspace.rs]"]
  node_persistence[("Durable state<br/>[postgres.rs]")]
  node_service_routing["Service endpoint routing<br/>[service_routing.rs]"]
end

subgraph group_runtime["Sandbox runtime"]
  node_supervisor["Supervisor<br/>[main.rs]"]
  node_sandbox["Sandbox process<br/>[main.rs]"]
  node_sandbox_backend["Sandbox backend<br/>[runtime.rs]"]
end

subgraph group_governance["Policy and access"]
  node_policy["Policy enforcement<br/>[lib.rs]"]
  node_kernel_controls["Kernel confinement<br/>[seccomp_notify.rs]"]
  node_prover["Policy prover<br/>[lib.rs]"]
  node_providers["Provider credentials<br/>[profiles.rs]"]
  node_supervisor_network["Network mediation<br/>[opa.rs]"]
end

subgraph group_extensibility["Drivers and extensions"]
  node_docker_driver["Docker driver<br/>[lib.rs]"]
  node_podman_driver["Podman driver<br/>[driver.rs]"]
  node_kubernetes_driver["Kubernetes driver<br/>[driver.rs]"]
  node_vm_driver["VM driver<br/>[driver.rs]"]
  node_extensions["Middleware and interceptors<br/>[routes.rs]"]
end

node_user(("Operator or agent developer"))

node_user -->|"manages sandboxes"| node_cli
node_user -->|"uses gateway API"| node_sdk
node_cli -.->|"issues operations"| node_gateway
node_sdk -->|"calls gRPC API"| node_gateway
node_gateway -->|"routes sandbox RPCs"| node_grpc_sandbox
node_gateway -->|"routes workspace RPCs"| node_grpc_workspace
node_grpc_sandbox -.->|"reads and writes"| node_persistence
node_grpc_workspace -.->|"reads and writes"| node_persistence
node_gateway -->|"routes endpoint traffic"| node_service_routing
node_gateway -.->|"coordinates runtime"| node_supervisor
node_supervisor -.->|"launches workload"| node_sandbox
node_sandbox -.->|"uses runtime backend"| node_sandbox_backend
node_sandbox -->|"confines system access"| node_kernel_controls
node_policy -->|"governs workload access"| node_sandbox
node_prover -->|"checks proposed changes"| node_policy
node_supervisor_network -->|"checks network access"| node_policy
node_providers -->|"supplies scoped credentials"| node_supervisor_network
node_supervisor -.->|"selects compute driver"| node_docker_driver
node_supervisor -.->|"selects compute driver"| node_podman_driver
node_supervisor -.->|"selects compute driver"| node_kubernetes_driver
node_supervisor -.->|"selects compute driver"| node_vm_driver
node_gateway -->|"supports extension hooks"| node_extensions

click node_cli "https://github.com/nvidia/openshell/blob/main/crates/openshell-cli/src/main.rs"
click node_sdk "https://github.com/nvidia/openshell/blob/main/crates/openshell-sdk/src/client.rs"
click node_gateway "https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/service.rs"
click node_grpc_sandbox "https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/sandbox.rs"
click node_grpc_workspace "https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/workspace.rs"
click node_persistence "https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/persistence/postgres.rs"
click node_service_routing "https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/service_routing.rs"
click node_supervisor "https://github.com/nvidia/openshell/blob/main/crates/openshell-supervisor/src/main.rs"
click node_sandbox "https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox/src/main.rs"
click node_sandbox_backend "https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox-backend/src/runtime.rs"
click node_policy "https://github.com/nvidia/openshell/blob/main/crates/openshell-policy/src/lib.rs"
click node_kernel_controls "https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox/src/linux/seccomp_notify.rs"
click node_prover "https://github.com/nvidia/openshell/blob/main/crates/openshell-prover/src/lib.rs"
click node_providers "https://github.com/nvidia/openshell/blob/main/crates/openshell-providers/src/profiles.rs"
click node_supervisor_network "https://github.com/nvidia/openshell/blob/main/crates/openshell-supervisor-network/src/opa.rs"
click node_docker_driver "https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-docker/src/lib.rs"
click node_podman_driver "https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-podman/src/driver.rs"
click node_kubernetes_driver "https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-kubernetes/src/driver.rs"
click node_vm_driver "https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-vm/src/driver.rs"
click node_extensions "https://github.com/nvidia/openshell/blob/main/crates/openshell-gateway-interceptors/src/routes.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_sdk toneBlue
class node_gateway,node_grpc_sandbox,node_grpc_workspace,node_persistence,node_service_routing toneAmber
class node_supervisor,node_sandbox,node_sandbox_backend toneMint
class node_policy,node_kernel_controls,node_prover,node_providers,node_supervisor_network toneRose
class node_docker_driver,node_podman_driver,node_kubernetes_driver,node_vm_driver,node_extensions,node_user toneIndigo
```

## Components

### User interfaces

- [OpenShell CLI](https://github.com/nvidia/openshell/blob/main/crates/openshell-cli/src/main.rs): `crates/openshell-cli/src/main.rs`
- [Rust SDK](https://github.com/nvidia/openshell/blob/main/crates/openshell-sdk/src/client.rs): `crates/openshell-sdk/src/client.rs`

### Gateway control plane

- [Gateway server](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/service.rs): `crates/openshell-server/src/grpc/service.rs`
- [Sandbox RPCs](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/sandbox.rs): `crates/openshell-server/src/grpc/sandbox.rs`
- [Workspace RPCs](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/grpc/workspace.rs): `crates/openshell-server/src/grpc/workspace.rs`
- [Durable state](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/persistence/postgres.rs): `crates/openshell-server/src/persistence/postgres.rs`
- [Service endpoint routing](https://github.com/nvidia/openshell/blob/main/crates/openshell-server/src/service_routing.rs): `crates/openshell-server/src/service_routing.rs`

### Sandbox runtime

- [Supervisor](https://github.com/nvidia/openshell/blob/main/crates/openshell-supervisor/src/main.rs): `crates/openshell-supervisor/src/main.rs`
- [Sandbox process](https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox/src/main.rs): `crates/openshell-sandbox/src/main.rs`
- [Sandbox backend](https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox-backend/src/runtime.rs): `crates/openshell-sandbox-backend/src/runtime.rs`

### Policy and access

- [Policy enforcement](https://github.com/nvidia/openshell/blob/main/crates/openshell-policy/src/lib.rs): `crates/openshell-policy/src/lib.rs`
- [Kernel confinement](https://github.com/nvidia/openshell/blob/main/crates/openshell-sandbox/src/linux/seccomp_notify.rs): `crates/openshell-sandbox/src/linux/seccomp_notify.rs`
- [Policy prover](https://github.com/nvidia/openshell/blob/main/crates/openshell-prover/src/lib.rs): `crates/openshell-prover/src/lib.rs`
- [Provider credentials](https://github.com/nvidia/openshell/blob/main/crates/openshell-providers/src/profiles.rs): `crates/openshell-providers/src/profiles.rs`
- [Network mediation](https://github.com/nvidia/openshell/blob/main/crates/openshell-supervisor-network/src/opa.rs): `crates/openshell-supervisor-network/src/opa.rs`

### Drivers and extensions

- [Docker driver](https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-docker/src/lib.rs): `crates/openshell-driver-docker/src/lib.rs`
- [Podman driver](https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-podman/src/driver.rs): `crates/openshell-driver-podman/src/driver.rs`
- [Kubernetes driver](https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-kubernetes/src/driver.rs): `crates/openshell-driver-kubernetes/src/driver.rs`
- [VM driver](https://github.com/nvidia/openshell/blob/main/crates/openshell-driver-vm/src/driver.rs): `crates/openshell-driver-vm/src/driver.rs`
- [Middleware and interceptors](https://github.com/nvidia/openshell/blob/main/crates/openshell-gateway-interceptors/src/routes.rs): `crates/openshell-gateway-interceptors/src/routes.rs`

### Other components

- **Operator or agent developer**

## Connections

- Operator or agent developer → OpenShell CLI: manages sandboxes (evidence: `README.md`)
- Operator or agent developer → Rust SDK: uses gateway API (evidence: `README.md`)
- OpenShell CLI → Gateway server: issues operations
- Rust SDK → Gateway server: calls gRPC API (evidence: `crates/openshell-sdk/src/client.rs`)
- Gateway server → Sandbox RPCs: routes sandbox RPCs (evidence: `crates/openshell-server/src/grpc/service.rs`)
- Gateway server → Workspace RPCs: routes workspace RPCs (evidence: `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 (evidence: `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 (evidence: `README.md`)
- Policy enforcement → Sandbox process: governs workload access (evidence: `README.md`)
- Policy prover → Policy enforcement: checks proposed changes (evidence: `README.md`)
- Network mediation → Policy enforcement: checks network access (evidence: `README.md`)
- Provider credentials → Network mediation: supplies scoped credentials (evidence: `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 (evidence: `README.md`)
