From b2252b18c0c415401e13828c06ae50b5c4677840 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sat, 26 Sep 2026 13:55:36 -0700 Subject: [PATCH 1/5] docs(readme): show Rust SDK installation command Signed-off-by: Drew Newberry --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 32b9b9bcbf..ed5cc57ecc 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ SDKs connect applications to an OpenShell gateway. They do not install the CLI. | Python | `uv add openshell` | [README](python/openshell/) | | TypeScript | `npm install @nvidia/openshell-sdk` (GitHub Packages) | [README](sdk/typescript/README.md) | | Go | `go get github.com/NVIDIA/OpenShell/sdk/go@latest` | [README](sdk/go/README.md) | -| Rust | Git dependency pinned to a release tag | [README](crates/openshell-sdk/README.md) | +| Rust | `cargo add openshell-sdk --git https://github.com/NVIDIA/OpenShell --tag ` | [Installation and usage](docs/sdk/rust.mdx) | ## Community From 522d395ad95fc19a0086e7c0f26bba366dbb5feb Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sat, 26 Sep 2026 14:09:45 -0700 Subject: [PATCH 2/5] docs(architecture): lead with policy enforcement Signed-off-by: Drew Newberry --- docs/about/architecture.mdx | 48 +++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx index 468fc922c7..beb51360f5 100644 --- a/docs/about/architecture.mdx +++ b/docs/about/architecture.mdx @@ -10,28 +10,50 @@ position: 2 ![OpenShell system architecture showing a trusted supervisor separated from a network-isolated sandbox workload. The workload can connect only to the supervisor.](../images/openshell-system-architecture.svg) -OpenShell separates control-plane state from sandbox enforcement. The gateway -owns sandbox state, policy, providers, and access, and uses formal verification -to evaluate proposed policy changes before they are approved. A compute driver -provisions the workload and its isolation boundary. - -The trusted supervisor runs outside the workload. `openshell-sandbox` runs -inside it, owns the agent process, and mediates its network requests. All other -workload egress is denied. The supervisor initiates one connection to the -gateway for configuration, credentials, logs, and interactive sessions. +OpenShell separates the untrusted agent workload from the components that +enforce its policy. The gateway manages sandbox state and creates each workload +through a compute driver. + +## Policy Enforcement + +In the Linux workload, Landlock limits filesystem access and seccomp mediates +network operations. `openshell-sandbox` owns the agent process, identifies the +program behind each network request, and forwards TCP and DNS requests to the +trusted supervisor outside the workload boundary. A separate network fence +denies direct workload egress except through the protected supervisor channel. + +The supervisor checks each request against the active policy. It opens approved +connections and adds provider credentials only to requests bound for authorized +endpoints; the agent does not receive the real credential values. When an agent +proposes a network rule through the [policy advisor](/how-it-works/policies/advisor), +the gateway's [policy prover](/how-it-works/policies/prover) uses formal +verification to check for risky new access. Findings block automatic approval +so a person can review the change. + +## Gateway and Workload Creation + +The gateway manages access, sandbox state, policies, and providers. When you +create a sandbox, its compute driver provisions a workload and a separate +supervisor, establishes their protected channel, and builds the isolation +boundary. The supervisor confirms that boundary before starting the agent. + +The supervisor initiates an outbound connection to the gateway for policy and +configuration updates, credentials, logs, and interactive sessions. The same +supervisor contract works across Docker, Podman, Kubernetes, and MicroVM +runtimes; each driver uses its platform's tools to create the boundary. ## What Each Piece Does | Component | What it does | |---|---| -| [Gateway](/how-it-works/gateways/overview) | Checks who you are and remembers everything about your sandboxes. It delivers policy and settings, attaches providers, decides who can do what, and coordinates connections into sandboxes. | -| [Compute runtime](/how-it-works/sandboxes/runtimes) | Creates the sandbox, starts the supervisor and the workload, sets up the private channel between them, and builds the network fence. It reports status back and cleans up when the sandbox goes away. | -| [Supervisor](#inside-the-sandbox-boundary) | Lives on the trusted side of the boundary. It checks requests against policy, supplies credentials, resolves DNS, opens approved connections, and keeps the link to the gateway alive. It works with every runtime through one [isolation backend](/extensibility/isolation-backends) interface to confirm the boundary, start the agent, run commands, forward connections, and see network requests. | | [OpenShell Sandbox](#inside-the-sandbox-boundary) | Lives inside the boundary with the agent. It owns the agent's processes, knows which program made each request, applies process controls, and forwards TCP and DNS traffic to the supervisor. | | [Outer network fence](/security/best-practices#deny-by-default-egress) | Denies all network egress from the workload except its protected connection to the supervisor. Each runtime builds this with its own native tools. | -| [Policy prover](/how-it-works/policies/prover) | Runs in the gateway and uses formal verification to check each proposed policy change before approval. It flags changes such as new credentialed reach, new HTTP methods, or access to cloud metadata endpoints, and any finding blocks auto-approval. It also ships as the standalone `openshell-prover` command for checking a policy against a boundary in CI. | +| [Supervisor](#inside-the-sandbox-boundary) | Lives on the trusted side of the boundary. It checks requests against policy, supplies credentials, resolves DNS, opens approved connections, and keeps the link to the gateway alive. It works with every runtime through one [isolation backend](/extensibility/isolation-backends) interface to confirm the boundary, start the agent, run commands, forward connections, and see network requests. | | [Policies](/how-it-works/policies/overview) | Describe what the agent can touch: files, processes, network destinations, API calls, and where provider credentials can go. | | [Providers](/how-it-works/providers/overview) | Connect a service name to a stored credential. The supervisor hands that credential out only where policy allows it. | +| [Policy prover](/how-it-works/policies/prover) | Runs in the gateway and uses formal verification to check agent-proposed network rules. It flags changes such as new credentialed reach, new HTTP methods, or access to cloud metadata endpoints; any finding blocks auto-approval. It also ships as the standalone `openshell-prover` command for checking a policy against a boundary in CI. | +| [Gateway](/how-it-works/gateways/overview) | Checks who you are and remembers everything about your sandboxes. It delivers policy and settings, attaches providers, decides who can do what, and coordinates connections into sandboxes. | +| [Compute runtime](/how-it-works/sandboxes/runtimes) | Creates the sandbox, starts the supervisor and the workload, sets up the private channel between them, and builds the network fence. It reports status back and cleans up when the sandbox goes away. | ## Inside the Sandbox Boundary From f98db2f781328d0874e981ebf02ef1249ab398bc Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sat, 26 Sep 2026 14:15:24 -0700 Subject: [PATCH 3/5] docs(architecture): reuse README how it works text Signed-off-by: Drew Newberry --- docs/about/architecture.mdx | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx index beb51360f5..0d2c3563a4 100644 --- a/docs/about/architecture.mdx +++ b/docs/about/architecture.mdx @@ -10,25 +10,12 @@ position: 2 ![OpenShell system architecture showing a trusted supervisor separated from a network-isolated sandbox workload. The workload can connect only to the supervisor.](../images/openshell-system-architecture.svg) -OpenShell separates the untrusted agent workload from the components that -enforce its policy. The gateway manages sandbox state and creates each workload -through a compute driver. - -## Policy Enforcement - -In the Linux workload, Landlock limits filesystem access and seccomp mediates -network operations. `openshell-sandbox` owns the agent process, identifies the -program behind each network request, and forwards TCP and DNS requests to the -trusted supervisor outside the workload boundary. A separate network fence -denies direct workload egress except through the protected supervisor channel. - -The supervisor checks each request against the active policy. It opens approved -connections and adds provider credentials only to requests bound for authorized -endpoints; the agent does not receive the real credential values. When an agent -proposes a network rule through the [policy advisor](/how-it-works/policies/advisor), -the gateway's [policy prover](/how-it-works/policies/prover) uses formal -verification to check for risky new access. Findings block automatic approval -so a person can review the change. +## How It Works + +OpenShell governs what agents can do in two ways: it instruments the kernel to enforce policy on every file access, system call, and network connection at runtime, and it uses formal verification to check what a policy change would allow before it is applied. + +- **Kernel-level enforcement.** Each agent runs in an isolated sandbox. Kernel controls confine which files it can access and which system calls it can make, and every network connection passes through a policy check before it leaves the sandbox. Agents never see real credentials; OpenShell adds them only to requests bound for approved endpoints. +- **Formally verified policy changes.** Before a policy change is approved, OpenShell uses formal verification to flag risky new access it would grant, such as reaching a new host with credentials or calling a new API method, so those changes wait for human review. ## Gateway and Workload Creation From e540d19479d78c6f6276ba5c44c7ae5b4cece31c Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sat, 26 Sep 2026 16:28:29 -0700 Subject: [PATCH 4/5] docs(architecture): refresh architecture page and diagrams Signed-off-by: Drew Newberry --- docs/about/architecture.mdx | 142 ++++++------- docs/images/openshell-isolation-backend.svg | 3 +- docs/images/openshell-kubernetes-runtime.svg | 3 +- .../openshell-sandbox-authentication.svg | 5 +- docs/images/openshell-sandbox-enforcement.svg | 40 ++-- docs/images/openshell-sandbox-protocol.svg | 5 +- docs/images/openshell-system-architecture.svg | 189 ++++++++++-------- 7 files changed, 190 insertions(+), 197 deletions(-) diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx index 0d2c3563a4..4332a1fc5f 100644 --- a/docs/about/architecture.mdx +++ b/docs/about/architecture.mdx @@ -10,131 +10,103 @@ position: 2 ![OpenShell system architecture showing a trusted supervisor separated from a network-isolated sandbox workload. The workload can connect only to the supervisor.](../images/openshell-system-architecture.svg) -## How It Works - OpenShell governs what agents can do in two ways: it instruments the kernel to enforce policy on every file access, system call, and network connection at runtime, and it uses formal verification to check what a policy change would allow before it is applied. - **Kernel-level enforcement.** Each agent runs in an isolated sandbox. Kernel controls confine which files it can access and which system calls it can make, and every network connection passes through a policy check before it leaves the sandbox. Agents never see real credentials; OpenShell adds them only to requests bound for approved endpoints. - **Formally verified policy changes.** Before a policy change is approved, OpenShell uses formal verification to flag risky new access it would grant, such as reaching a new host with credentials or calling a new API method, so those changes wait for human review. -## Gateway and Workload Creation - -The gateway manages access, sandbox state, policies, and providers. When you -create a sandbox, its compute driver provisions a workload and a separate -supervisor, establishes their protected channel, and builds the isolation -boundary. The supervisor confirms that boundary before starting the agent. - -The supervisor initiates an outbound connection to the gateway for policy and -configuration updates, credentials, logs, and interactive sessions. The same -supervisor contract works across Docker, Podman, Kubernetes, and MicroVM -runtimes; each driver uses its platform's tools to create the boundary. +The **gateway** is the control plane: it manages the lifecycle of sandboxes and +provides connectivity and management of sandboxes to end users and operators. +When you create a sandbox, its **compute driver** provisions a **workload** and +a separate **supervisor**, establishes their protected channel, and builds the +isolation boundary; the **supervisor** confirms that boundary before starting the +**agent** and then connects back to the gateway for policy, credentials, logs, +and interactive sessions. ## What Each Piece Does | Component | What it does | |---|---| -| [OpenShell Sandbox](#inside-the-sandbox-boundary) | Lives inside the boundary with the agent. It owns the agent's processes, knows which program made each request, applies process controls, and forwards TCP and DNS traffic to the supervisor. | -| [Outer network fence](/security/best-practices#deny-by-default-egress) | Denies all network egress from the workload except its protected connection to the supervisor. Each runtime builds this with its own native tools. | -| [Supervisor](#inside-the-sandbox-boundary) | Lives on the trusted side of the boundary. It checks requests against policy, supplies credentials, resolves DNS, opens approved connections, and keeps the link to the gateway alive. It works with every runtime through one [isolation backend](/extensibility/isolation-backends) interface to confirm the boundary, start the agent, run commands, forward connections, and see network requests. | +| [**Sandbox**](#inside-the-sandbox-boundary) | Lives inside the boundary with the agent. It owns the agent's processes, knows which program made each request, applies process controls, and forwards TCP and DNS traffic to the **supervisor**. | +| [Outer network fence](/security/best-practices#deny-by-default-egress) | Denies all network egress from the workload except its protected connection to the **supervisor**. Each runtime builds this with its own native tools. | +| [**Supervisor**](#inside-the-sandbox-boundary) | Lives on the trusted side of the boundary. It checks requests against policy, supplies credentials, resolves DNS, opens approved connections, and keeps the link to the gateway alive. It works with every runtime through one [isolation backend](/extensibility/isolation-backends) interface to confirm the boundary, start the agent, run commands, forward connections, and see network requests. | | [Policies](/how-it-works/policies/overview) | Describe what the agent can touch: files, processes, network destinations, API calls, and where provider credentials can go. | -| [Providers](/how-it-works/providers/overview) | Connect a service name to a stored credential. The supervisor hands that credential out only where policy allows it. | +| [Providers](/how-it-works/providers/overview) | Connect a service name to a stored credential. The **supervisor** hands that credential out only where policy allows it. | | [Policy prover](/how-it-works/policies/prover) | Runs in the gateway and uses formal verification to check agent-proposed network rules. It flags changes such as new credentialed reach, new HTTP methods, or access to cloud metadata endpoints; any finding blocks auto-approval. It also ships as the standalone `openshell-prover` command for checking a policy against a boundary in CI. | | [Gateway](/how-it-works/gateways/overview) | Checks who you are and remembers everything about your sandboxes. It delivers policy and settings, attaches providers, decides who can do what, and coordinates connections into sandboxes. | -| [Compute runtime](/how-it-works/sandboxes/runtimes) | Creates the sandbox, starts the supervisor and the workload, sets up the private channel between them, and builds the network fence. It reports status back and cleans up when the sandbox goes away. | +| [Compute runtime](/how-it-works/sandboxes/runtimes) | Creates the sandbox, starts the **supervisor** and the workload, sets up the private channel between them, and builds the network fence. It reports status back and cleans up when the sandbox goes away. | ## Inside the Sandbox Boundary -The supervisor and `openshell-sandbox` sit on opposite sides of the boundary. -The supervisor is trusted and makes the decisions. `openshell-sandbox` shares +The **supervisor** and **sandbox** sit on opposite sides of the boundary. +The **supervisor** is trusted and makes the decisions. The **sandbox** shares the boundary with the untrusted agent, so it never makes policy decisions. It -reports what the agent is trying to do and lets the supervisor decide. +reports what the agent is trying to do and lets the **supervisor** decide. -`openshell-sandbox` launches the agent as an owned child and provides exec, +The **sandbox** launches the agent as an owned child and provides exec, terminal streams, signals, process status, and loopback forwarding. In the current Linux backend, the workload uses one non-root identity and no Linux capabilities. Landlock limits filesystem access; seccomp user notification -stages network operations. The sandbox identifies the calling executable from +stages network operations. The **sandbox** identifies the calling executable from trusted process observations. ![OpenShell sandbox enforcement flow showing the network-isolated sandbox and trusted supervisor as separate boundaries. The supervisor channel is the workload's only allowed egress path.](../images/openshell-sandbox-enforcement.svg) -### The protected channel +### Mediated Channel -The supervisor and `openshell-sandbox` talk over the OpenShell Sandbox Protocol: +The **supervisor** and **sandbox** talk over the OpenShell Sandbox Protocol: one mutually authenticated HTTP/2 connection that carries many independent streams. The compute driver picks the transport: a Unix socket for Docker and Podman, TCP for Kubernetes, or vsock for MicroVM. Authentication and protocol -behavior are the same on all of them. The supervisor presents a +behavior are the same on all of them. The **supervisor** presents a sandbox-specific credential, as described in [How Components Authenticate](#how-components-authenticate). -![OpenShell Sandbox Protocol showing the trusted supervisor and the network-isolated OpenShell Sandbox connected by one authenticated connection with separate control, DNS, and per-connection TCP streams. The agent reaches the supervisor only through the OpenShell Sandbox.](../images/openshell-sandbox-protocol.svg) +![OpenShell Sandbox Protocol showing the trusted supervisor and the network-isolated sandbox connected by one authenticated connection with separate control, DNS, and per-connection TCP streams. The agent reaches the supervisor only through the sandbox.](../images/openshell-sandbox-protocol.svg) Each TCP connection gets its own stream with its own backpressure, so a slow download can't block DNS, exec, or process control. -| Guarantee | How `openshell-sandbox` provides it | What the supervisor gets | +| Guarantee | How the **sandbox** provides it | What the **supervisor** gets | |---|---|---| | Process ownership | Runs the agent as an owned child and keeps its process and terminal state. | Handles to wait on, attach to, signal, exec in, and stop the agent. | | Program identity | Identifies the calling program from trusted `/proc` data. | The real program behind each request, not a path the agent claims. | | Network mediation | Intercepts TCP opens and DNS queries with seccomp and hands them over. | Requests that wait for a policy decision before going anywhere. | -| Fail closed | Holds launch until the supervisor confirms, and freezes the agent if the connection drops. | A short window to reconnect, or a stopped workload. | +| Fail closed | Holds launch until the **supervisor** confirms, and freezes the agent if the connection drops. | A short window to reconnect, or a stopped workload. | Together these mean the agent can't run before its controls are confirmed, signals and exec reach only this sandbox's processes, and the agent can't get around TCP or DNS mediation. -### Starting an agent safely - -The supervisor's `OpenShellRuntimeBackend` implements the shared -[Isolation Backend](/extensibility/isolation-backends) interface using the -Sandbox Protocol. Before the agent runs, it walks through a fixed series of -steps: - -```text -Attach → Bound → Confirmed → Ready → Running -``` - -The compute driver supplies the transport and a runtime descriptor. The backend -binds that descriptor to the admitted sandbox during attach, then confirms the -workload identity, launch controls, and outer network fence before starting the -agent. Each step must succeed before the next one begins. A stale or mismatched -boundary cannot launch the workload. - ### How a network request travels -Say the agent tries to call an API. Here's what happens, and it works the same -way on every runtime: - 1. The agent opens a TCP connection or makes a DNS lookup. -2. `openshell-sandbox` notes which program made the request. -3. The request travels over the Sandbox Protocol to the supervisor. -4. The supervisor checks the request against policy and adds any credentials the - policy allows. -5. If the request is allowed, the supervisor opens the real connection and - relays the traffic. - -The protected channel to the supervisor is the only network path allowed out of -the workload boundary. The outer fence denies all other network egress. The -agent cannot reach an external service, the gateway, DNS, or another private -address directly. +2. The **sandbox** identifies the calling program. +3. The request travels over the Sandbox Protocol to the **supervisor**. +4. The **supervisor** checks it against policy and adds any credentials policy + allows. +5. If allowed, the **supervisor** opens the real connection and relays traffic. + +The mediated channel to the **supervisor** is the workload's only allowed egress +path. The outer fence denies everything else, so the agent can't reach a +service, the gateway, DNS, or another private address directly. ## How Each Runtime Builds the Boundary Every runtime follows the same contract, but each one uses the tools it already -has to place the supervisor, connect it to the sandbox, and fence off the +has to place the **supervisor**, connect it to the **sandbox**, and fence off the network. -| Runtime | Where the supervisor runs | How it talks to the sandbox | How direct egress is blocked | +| Runtime | Where the **supervisor** runs | How it talks to the **sandbox** | How direct egress is blocked | |---|---|---|---| | Docker | Its own container | Authenticated Unix socket on a driver-owned volume | Workload container has networking turned off | | Podman | Its own container | Authenticated Unix socket on a driver-owned volume | Workload container has networking turned off | -| Kubernetes | Its own pod | Private service with mutual TLS | NetworkPolicy allows only the supervisor service | +| Kubernetes | Its own pod | Private service with mutual TLS | NetworkPolicy allows only the **supervisor** service | | VM | A process on the host | Authenticated vsock | Guest has no network device | The runtime's job is to build the boundary and prove it's in place. It never decides whether a request is allowed. That decision always belongs to the shared -supervisor and policy engine, which is why the same policy behaves the same way +**supervisor** and policy engine, which is why the same policy behaves the same way everywhere. Runtimes can differ in how they report readiness and which features they @@ -146,38 +118,38 @@ do. Three connections tie a sandbox together. The gateway is the only component that signs credentials, and every credential names exactly one sandbox. -![OpenShell sandbox authentication showing the compute driver giving the supervisor a bootstrap credential, the gateway issuing a gateway JWT and sandbox JWT, and the supervisor presenting the sandbox JWT over mutual TLS to the OpenShell Sandbox, which holds only the gateway's public key.](../images/openshell-sandbox-authentication.svg) +![OpenShell sandbox authentication showing the compute driver giving the supervisor a bootstrap credential, the gateway issuing a gateway JWT and sandbox JWT, and the supervisor presenting the sandbox JWT over mutual TLS to the sandbox, which holds only the gateway's public key.](../images/openshell-sandbox-authentication.svg) | Connection | Who connects | How it's protected | |---|---|---| -| Supervisor to gateway | The supervisor dials out to the gateway. | A gateway JWT, over TLS when the gateway has TLS enabled. | -| Supervisor to `openshell-sandbox` | The supervisor dials into the workload over the driver's private channel. | Mutual TLS, plus a sandbox JWT. | -| Agent to supervisor | The agent never connects directly. `openshell-sandbox` relays its traffic over the connection above. | Covered by the supervisor-to-sandbox channel. | +| **Supervisor** to gateway | The **supervisor** dials out to the gateway. | A gateway JWT, over TLS when the gateway has TLS enabled. | +| **Supervisor** to **sandbox** | The **supervisor** dials into the workload over the driver's private channel. | Mutual TLS, plus a sandbox JWT. | +| Agent to **supervisor** | The agent never connects directly. The **sandbox** relays its traffic over the connection above. | Covered by the supervisor-to-sandbox channel. | ### Getting the first credential -The supervisor needs a starting credential to prove which sandbox it belongs +The **supervisor** needs a starting credential to prove which sandbox it belongs to. How it gets one depends on the runtime: -- **Docker, Podman, and MicroVM.** The driver hands the supervisor its initial - tokens directly, in files only the supervisor can read. -- **Kubernetes.** The supervisor presents its pod's ServiceAccount token. The +- **Docker, Podman, and MicroVM.** The driver hands the **supervisor** its initial + tokens directly, in files only the **supervisor** can read. +- **Kubernetes.** The **supervisor** presents its pod's ServiceAccount token. The gateway asks the Kubernetes driver to verify the token and confirm that the pod belongs to the expected sandbox before it issues any JWTs. Either way, the gateway checks the claim against its own record of the sandbox before returning credentials. -### Two JWTs, two jobs +### Gateway and Sandbox JWTs The gateway issues a pair of JWTs for each run of a sandbox: -- **Gateway JWT.** Sent with every supervisor call to the gateway. It allows - only the calls a supervisor needs, such as fetching policy, pushing logs, and +- **Gateway JWT.** Sent with every **supervisor** call to the gateway. It allows + only the calls a **supervisor** needs, such as fetching policy, pushing logs, and relaying sessions. It is not a user credential and can't manage other sandboxes. -- **Sandbox JWT.** Sent with every supervisor call to `openshell-sandbox`. - `openshell-sandbox` holds only the gateway's public key, so it can verify the +- **Sandbox JWT.** Sent with every **supervisor** call to the **sandbox**. + The **sandbox** holds only the gateway's public key, so it can verify the token but can never create one. Each token works only on its own connection. Both are bound to one sandbox and @@ -187,9 +159,9 @@ working. ### Renewing and revoking -The supervisor keeps its tokens in memory and renews both together before they +The **supervisor** keeps its tokens in memory and renews both together before they expire. Renewal works only while the sandbox still exists, so deleting a -sandbox cuts off its supervisor. +sandbox cuts off its **supervisor**. Shared deployments, such as Kubernetes, should set `gateway_jwt.ttl_secs` so tokens expire. Local single-user gateways can leave it unset, which issues @@ -197,20 +169,20 @@ tokens that last for the life of the sandbox run. ### What the agent can see -The agent shares its side of the boundary with `openshell-sandbox`, so -`openshell-sandbox` holds nothing worth stealing: no gateway signing key, no +The agent shares its side of the boundary with the **sandbox**, so +the **sandbox** holds nothing worth stealing: no gateway signing key, no gateway JWT, and no provider credentials. It can verify that it's talking to -the right supervisor, but it can't impersonate one. +the right **supervisor**, but it can't impersonate one. -If the supervisor disconnects, `openshell-sandbox` freezes the agent. Only the -same supervisor process can reconnect and resume it. A new supervisor can't +If the **supervisor** disconnects, the **sandbox** freezes the agent. Only the +same **supervisor** process can reconnect and resume it. A new **supervisor** can't take over a running sandbox, even with valid credentials. ## Working With Your Existing Infrastructure OpenShell plugs into the tools you already use, including container runtimes, schedulers, secret stores, identity providers, image pipelines, storage, and -device plugins. The gateway and supervisor define how OpenShell behaves. +device plugins. The gateway and **supervisor** define how OpenShell behaves. Drivers translate that behavior into whatever your platform understands and report back what happened. This keeps platform-specific details out of the core control plane and the policy model. diff --git a/docs/images/openshell-isolation-backend.svg b/docs/images/openshell-isolation-backend.svg index 0955086d0b..7561c29d8c 100644 --- a/docs/images/openshell-isolation-backend.svg +++ b/docs/images/openshell-isolation-backend.svg @@ -18,6 +18,7 @@ .tiny { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; } .box { fill: #ffffff; stroke: #cbd5e1; stroke-width: 2; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-start: url(#arrow-green); marker-end: url(#arrow-green); } @@ -52,7 +53,7 @@ - + openshell-sandbox workload-side server diff --git a/docs/images/openshell-kubernetes-runtime.svg b/docs/images/openshell-kubernetes-runtime.svg index 112cde55d2..7b26ae8186 100644 --- a/docs/images/openshell-kubernetes-runtime.svg +++ b/docs/images/openshell-kubernetes-runtime.svg @@ -19,6 +19,7 @@ .box { fill: #ffffff; stroke: #cbd5e1; stroke-width: 2; } .soft { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .green { fill: #f2f9e8; stroke: #76b900; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } @@ -68,7 +69,7 @@ WORKLOAD POD - + OpenShell Sandbox process and syscall boundary diff --git a/docs/images/openshell-sandbox-authentication.svg b/docs/images/openshell-sandbox-authentication.svg index d2beafc8bf..ecebf17c27 100644 --- a/docs/images/openshell-sandbox-authentication.svg +++ b/docs/images/openshell-sandbox-authentication.svg @@ -20,6 +20,7 @@ .soft { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; } .green { fill: #f2f9e8; stroke: #76b900; stroke-width: 2.5; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-end: url(#arrow-green); } @@ -55,8 +56,8 @@ - - OpenShell Sandbox + + Sandbox VERIFIES, NEVER SIGNS Gateway public key only Checks the sandbox JWT diff --git a/docs/images/openshell-sandbox-enforcement.svg b/docs/images/openshell-sandbox-enforcement.svg index 6d7b7bf7a6..ef991a3aa3 100644 --- a/docs/images/openshell-sandbox-enforcement.svg +++ b/docs/images/openshell-sandbox-enforcement.svg @@ -1,9 +1,9 @@ - + OpenShell sandbox enforcement flow - The sandbox workload and trusted supervisor are separate boundaries. All workload network egress is denied except the authenticated Sandbox Protocol connection to the supervisor. + The sandbox workload and trusted supervisor are separate boundaries. All workload network egress is denied except the authenticated Sandbox Protocol connection to the supervisor. The OpenShell Sandbox holds a local policy.local file that carries proposed policy changes to the supervisor's policy enforcement for review, and receives the reloaded policy back. @@ -21,13 +21,16 @@ .soft { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; } .green { fill: #f2f9e8; stroke: #76b900; stroke-width: 2.5; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-end: url(#arrow-green); } .blocked { fill: none; stroke: #c2413b; stroke-width: 2.5; stroke-dasharray: 8 7; } + .policy { fill: none; stroke: #475569; stroke-width: 2; stroke-dasharray: 6 6; marker-end: url(#arrow); } + .chip { fill: #eff6ff; stroke: #3b82f6; stroke-width: 1.5; } - + @@ -37,10 +40,12 @@ Agent process - - OpenShell - Sandbox - process owner + + OpenShell + Sandbox + process owner + + policy.local 1 @@ -76,6 +81,9 @@ Checks destination, binary, L7 rules, and credentials + + POLICY.LOCAL PROPOSE / RELOAD (ASYNC) + Upstream service @@ -83,23 +91,5 @@ 4 - - LAUNCH GATE - - - - ATTACH - - BOUND - - CONFIRMED - - READY - - ✓ - RUNNING - - - Agent cannot start until the boundary is confirmed diff --git a/docs/images/openshell-sandbox-protocol.svg b/docs/images/openshell-sandbox-protocol.svg index 51afd7e860..37806a8325 100644 --- a/docs/images/openshell-sandbox-protocol.svg +++ b/docs/images/openshell-sandbox-protocol.svg @@ -18,6 +18,7 @@ .tiny { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; } .box { fill: #ffffff; stroke: #cbd5e1; stroke-width: 2; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-start: url(#arrow-green); marker-end: url(#arrow-green); } @@ -44,8 +45,8 @@ - - OpenShell Sandbox + + Sandbox PROCESS AND SYSCALL BOUNDARY Owns the agent process Identifies each program diff --git a/docs/images/openshell-system-architecture.svg b/docs/images/openshell-system-architecture.svg index c910ff8c5a..4649dd91fe 100644 --- a/docs/images/openshell-system-architecture.svg +++ b/docs/images/openshell-system-architecture.svg @@ -1,9 +1,9 @@ - + OpenShell system architecture - User interfaces connect to the gateway, which uses the policy prover to formally verify proposed policy changes before approval. The OpenShell Runtime places a trusted supervisor separately from a network-isolated sandbox workload. The workload's only allowed network path is its mediated connection to the supervisor, which connects to approved external services. + User interfaces connect to the gateway, which uses the policy prover to formally verify proposed policy changes before approval. The OpenShell Runtime places a trusted supervisor separately from a network-isolated sandbox workload. The workload's only allowed network path is its mediated connection to the supervisor, which connects to approved external services. The policy lifecycle strip shows the supervisor proposing a policy change, the gateway's policy prover checking it, a human approving it, and the supervisor reloading the approved policy. @@ -21,96 +21,123 @@ .soft { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; } .green { fill: #f2f9e8; stroke: #76b900; stroke-width: 2.5; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } + .owned { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-end: url(#arrow-green); } .blocked { fill: none; stroke: #c2413b; stroke-width: 2.5; stroke-dasharray: 8 7; } + .dashed { fill: none; stroke: #475569; stroke-width: 2; stroke-dasharray: 6 6; marker-end: url(#arrow); } - + USER INTERFACES - - - CLI - - SDK - - TUI + + + CLI + + SDK + + TUI EXTERNAL SERVICES - - - Services - APIs and tools - - Models - inference APIs - - GATEWAY (CONTROL PLANE) - - - API Server - API, authentication, lifecycle, relays - - Policy prover - formal verification of policy changes - - Durable state - sandboxes · policies · providers · settings - - Compute driver - places and fences each sandbox - - - - - OPENSHELL RUNTIME (DATA PLANE) - - - - Supervisor - GOVERNS THE AGENT - Policy evaluation - Credential resolution - DNS and proxying - Agent session multiplexing - - Maintains the gateway session - - - SANDBOX · NETWORK ISOLATED - (CONTAINER · VM) - - OpenShell Sandbox - process owner and syscall boundary - - Agent - untrusted workload - - - - MEDIATED CHANNEL - - - - - - WORKLOAD NETWORK RULE - Deny all egress - except to the supervisor - - - gRPC / HTTP - - OUTBOUND - SESSION - - PROVISION - - - POLICY-APPROVED EGRESS + + + Services + APIs and tools + + Models + inference APIs + + GATEWAY (CONTROL PLANE) + + + API Server + API, authentication, lifecycle, relays + + Policy prover + + Durable state + sandboxes · policies · providers · settings + + Compute driver + places and fences each sandbox + + + + + OPENSHELL RUNTIME (DATA PLANE) + + + + Supervisor + GOVERNS THE AGENT + Policy evaluation + Credential resolution + DNS and proxying + Agent session multiplexing + + Maintains the gateway session + + + SANDBOX · NETWORK ISOLATED + (CONTAINER · VM) + + Sandbox + process owner and syscall boundary + + Agent + untrusted workload + + + + MEDIATED CHANNEL + + + + + + WORKLOAD NETWORK RULE + Deny all egress + except to the supervisor + + + gRPC / HTTP + + + + + POLICY-APPROVED EGRESS + + POLICY LIFECYCLE + + + + SUPERVISOR PROPOSES + + APPROVED POLICY RELOADED + + + Policy reloads + supervisor retries + + + You approve + manual by default + or auto — no new risk found + + + Gateway prover checks + flags risky new access + + + Agent proposes + via policy.local + + + + From 808df44adf19a8d8c9bad25f0a2665223cdc9acd Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sat, 26 Sep 2026 16:28:29 -0700 Subject: [PATCH 5/5] docs(extensibility): simplify extension points diagram and overview Redraw the extension points diagram as two left-to-right rows for the data plane and control plane, describe which layers each extension point extends, and move authentication after Building Extensions as Authenticating Extensions with updated cross-page links. Signed-off-by: Drew Newberry --- docs/extensibility/gateway-interceptors.mdx | 2 +- docs/extensibility/overview.mdx | 92 ++++++------ .../supervisor-middleware/configure.mdx | 4 +- .../supervisor-middleware/index.mdx | 2 +- docs/images/openshell-extension-points.svg | 139 ++++++------------ 5 files changed, 103 insertions(+), 136 deletions(-) diff --git a/docs/extensibility/gateway-interceptors.mdx b/docs/extensibility/gateway-interceptors.mdx index 212c3fe245..20600fabf6 100644 --- a/docs/extensibility/gateway-interceptors.mdx +++ b/docs/extensibility/gateway-interceptors.mdx @@ -97,7 +97,7 @@ phases = ["validate"] The gateway supports `http://`, `https://`, and `unix://` interceptor endpoints. When gateway JWT signing is configured, authenticated network interceptors use `https://`; Unix sockets remain available for local integrations. HTTPS uses platform trust roots unless `tls_ca_cert_path` supplies a private CA, and normal hostname verification remains enabled. The gateway calls `Describe` and builds an immutable execution plan during startup. An unavailable service, invalid manifest, missing credential, or unauthorized configured binding prevents the gateway from starting. -When gateway JWT signing is configured, the gateway authenticates every call to the interceptor with a short-lived token. [Extension Authentication](/extensibility/overview#authentication) describes how your service validates it. Set `allow_insecure_transport = true` to use a plaintext `http://` endpoint without authentication, for local development or on a network that already authenticates callers. +When gateway JWT signing is configured, the gateway authenticates every call to the interceptor with a short-lived token. [Authenticating Extensions](/extensibility/overview#authenticating-extensions) describes how your service validates it. Set `allow_insecure_transport = true` to use a plaintext `http://` endpoint without authentication, for local development or on a network that already authenticates callers. Registration is static. Restart the gateway after adding, removing, or changing an interceptor. See [Gateway Configuration](/how-it-works/gateways/configuration#gateway-interceptors) for the complete field reference. diff --git a/docs/extensibility/overview.mdx b/docs/extensibility/overview.mdx index 952d6e925f..149df13d96 100644 --- a/docs/extensibility/overview.mdx +++ b/docs/extensibility/overview.mdx @@ -8,13 +8,21 @@ description: "Understand how OpenShell adapts to deployment-specific infrastruct keywords: "OpenShell Extensions, Middleware, Interceptors, Drivers, Isolation Backends, Protocol Negotiation" --- -![OpenShell extension points across the gateway and runtime: gateway interceptors, compute and credential drivers, supervisor middleware, and isolation backends.](../images/openshell-extension-points.svg) +![OpenShell extension points. Data plane: the sandboxed agent reaches the supervisor through the isolation backend, and supervisor middleware processes requests before they reach models and APIs. Control plane: you reach the gateway through interceptors, and gateway drivers connect it to runtimes and secret stores.](../images/openshell-extension-points.svg) Extensibility sits at the core of OpenShell. OpenShell is designed to run everywhere and adapt to the infrastructure, governance, and workload requirements of each deployment. Its extension points add deployment-specific behavior while preserving the same API, policy model, and security boundaries. +You can extend each layer of OpenShell: + +- **Control plane:** Gateway interceptors govern API operations. +- **Data plane:** Middleware processes agent traffic, and isolation backends + control the sandboxed workload. +- **Infrastructure:** Drivers connect OpenShell to compute runtimes and secret + stores. + ## Extension Points ### [Middleware](/extensibility/supervisor-middleware) @@ -42,46 +50,6 @@ Isolation backends connect the supervisor to the sandbox runtime. They provide a consistent contract for process launch, terminal streams, signals, status, and runtime-specific isolation inside the provisioned workload. -## Authentication - -When the gateway has JWT signing configured, OpenShell sends a short-lived bearer token with every call to a [gateway interceptor](/extensibility/gateway-interceptors) or [supervisor middleware](/extensibility/supervisor-middleware) service. Validate it to confirm the call comes from your gateway or one of its sandboxes. - -| Claim | Value | -|---|---| -| `iss` | `openshell-gateway:` | -| `aud` | The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:` or `urn:openshell:extension:middleware:`. | -| `caller_kind` | `gateway`, or `supervisor` for middleware calls from a sandbox. | -| `sandbox_id` | The calling sandbox, when `caller_kind` is `supervisor`. | - -### Validate Each Token - -Get the gateway ID and public signing key (or JWKS) from the gateway operator and configure them in your service. Don't trust a key discovered from an unverified source. To pick up rotated keys, fetch `/.well-known/openid-configuration` from the gateway over TLS and follow its `jwks_uri`. - -For each request, check that: - -- `typ` is `openshell-ext+jwt` and `alg` is `EdDSA`. Pin the algorithm; don't read it from the token. -- The signature, expiry, and exact audience are valid. -- `iss` is `openshell-gateway:`, not the gateway URL. -- `caller_kind` and `sandbox_id` match what your service accepts. - -OpenShell reuses a token until it rotates, so don't reject a repeated `jti`. - -Services must use `https://` endpoints. OpenShell verifies the certificate and hostname against platform roots, or against `tls_ca_cert_path` for a private CA. - -### Confirm the Audience at Startup - -Return your expected audience in the `expected_audience` field of your `Describe` manifest. The gateway refuses to start if it doesn't match the configured `audience`. Leave it empty to skip the check. - -### Run Without Authentication - -Set `allow_insecure_transport = true` on a registration to use a plaintext `http://` endpoint with no token. Your service then can't tell OpenShell apart from any other client, and the gateway logs a warning at every startup. Use this only for local development or on a network that already authenticates callers. - -### Current Limitations - -- Tokens are bearer credentials: a captured token works until it expires. -- Extension tokens share the gateway's signing key, so you can't rotate or revoke them separately. -- mTLS client authentication and overlapping key rotation aren't available. - ## Building Extensions Start with the narrowest extension point that owns the behavior you need. Keep @@ -112,7 +80,7 @@ Use Unix domain sockets when the gateway and extension share a host. Use `https://` when a service crosses a host or pod boundary. Plaintext `http://` is intended for explicitly enabled development deployments; authenticated network extensions use TLS and short-lived gateway-issued credentials. Refer -to [Authentication](#authentication) for how services validate those credentials. +to [Authenticating Extensions](#authenticating-extensions) for how services validate those credentials. The [governance interceptor example](https://github.com/NVIDIA/OpenShell/tree/main/examples/governance-interceptor) and [content guard middleware example](https://github.com/NVIDIA/OpenShell/tree/main/examples/supervisor-middleware-content-guard) @@ -137,3 +105,43 @@ extensions follow the same compatibility checks. Use `openshell gateway info` to inspect the negotiated extension families, implementation versions, protocol versions, and capabilities active on a gateway. + +## Authenticating Extensions + +When the gateway has JWT signing configured, OpenShell sends a short-lived bearer token with every call to a [gateway interceptor](/extensibility/gateway-interceptors) or [supervisor middleware](/extensibility/supervisor-middleware) service. Validate it to confirm the call comes from your gateway or one of its sandboxes. + +| Claim | Value | +|---|---| +| `iss` | `openshell-gateway:` | +| `aud` | The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:` or `urn:openshell:extension:middleware:`. | +| `caller_kind` | `gateway`, or `supervisor` for middleware calls from a sandbox. | +| `sandbox_id` | The calling sandbox, when `caller_kind` is `supervisor`. | + +### Validate Each Token + +Get the gateway ID and public signing key (or JWKS) from the gateway operator and configure them in your service. Don't trust a key discovered from an unverified source. To pick up rotated keys, fetch `/.well-known/openid-configuration` from the gateway over TLS and follow its `jwks_uri`. + +For each request, check that: + +- `typ` is `openshell-ext+jwt` and `alg` is `EdDSA`. Pin the algorithm; don't read it from the token. +- The signature, expiry, and exact audience are valid. +- `iss` is `openshell-gateway:`, not the gateway URL. +- `caller_kind` and `sandbox_id` match what your service accepts. + +OpenShell reuses a token until it rotates, so don't reject a repeated `jti`. + +Services must use `https://` endpoints. OpenShell verifies the certificate and hostname against platform roots, or against `tls_ca_cert_path` for a private CA. + +### Confirm the Audience at Startup + +Return your expected audience in the `expected_audience` field of your `Describe` manifest. The gateway refuses to start if it doesn't match the configured `audience`. Leave it empty to skip the check. + +### Run Without Authentication + +Set `allow_insecure_transport = true` on a registration to use a plaintext `http://` endpoint with no token. Your service then can't tell OpenShell apart from any other client, and the gateway logs a warning at every startup. Use this only for local development or on a network that already authenticates callers. + +### Current Limitations + +- Tokens are bearer credentials: a captured token works until it expires. +- Extension tokens share the gateway's signing key, so you can't rotate or revoke them separately. +- mTLS client authentication and overlapping key rotation aren't available. diff --git a/docs/extensibility/supervisor-middleware/configure.mdx b/docs/extensibility/supervisor-middleware/configure.mdx index eec1bceee0..7ea8183af3 100644 --- a/docs/extensibility/supervisor-middleware/configure.mdx +++ b/docs/extensibility/supervisor-middleware/configure.mdx @@ -53,7 +53,7 @@ timeout = "500ms" - Token audience. Refer to [Extension Authentication](/extensibility/overview#authentication). + Token audience. Refer to [Authenticating Extensions](/extensibility/overview#authenticating-extensions). @@ -62,7 +62,7 @@ timeout = "500ms" At startup, the gateway contacts every registered service to read its capabilities and verify [protocol compatibility](/extensibility/overview#protocol-negotiation). The gateway does not start if a service is unavailable or incompatible. [Gateway Configuration](/how-it-works/gateways/configuration#supervisor-middleware-services) describes the full TOML context. -When the gateway has JWT signing configured, OpenShell authenticates every call to your service with a short-lived token. [Extension Authentication](/extensibility/overview#authentication) describes how your service validates it. +When the gateway has JWT signing configured, OpenShell authenticates every call to your service with a short-lived token. [Authenticating Extensions](/extensibility/overview#authenticating-extensions) describes how your service validates it. ## Attach Middleware in Policy diff --git a/docs/extensibility/supervisor-middleware/index.mdx b/docs/extensibility/supervisor-middleware/index.mdx index ce084185a0..c17a79d252 100644 --- a/docs/extensibility/supervisor-middleware/index.mdx +++ b/docs/extensibility/supervisor-middleware/index.mdx @@ -98,7 +98,7 @@ These guides cover the rest of the service contract: When OpenShell calls your service, what it receives, and what it can return for HTTP requests, HTTP responses, and WebSocket messages. - + How to verify that calls to your service come from your OpenShell gateway. diff --git a/docs/images/openshell-extension-points.svg b/docs/images/openshell-extension-points.svg index 4f433725de..845f2c02f5 100644 --- a/docs/images/openshell-extension-points.svg +++ b/docs/images/openshell-extension-points.svg @@ -1,9 +1,9 @@ - + OpenShell extension points - Gateway interceptors and drivers extend the control plane. Middleware and isolation backends extend the OpenShell runtime. Middleware connects approved traffic to external services, while the compute driver provisions the sandbox boundary. + Two rows read left to right. Data plane: the sandboxed agent reaches the supervisor through the isolation backend, and supervisor middleware processes requests before they reach models and APIs. Control plane: you reach the gateway through interceptors, and gateway drivers connect it to runtimes and secret stores. @@ -16,101 +16,60 @@ .label { font: 700 18px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #111827; } .small { font: 500 14px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; } .tag { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #579000; letter-spacing: .06em; } - .tiny { font: 700 12px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #475569; } - .panel { fill: #f8fafc; stroke: #cbd5e1; stroke-width: 2; } .box { fill: #ffffff; stroke: #cbd5e1; stroke-width: 2; } .trusted { fill: #eff6ff; stroke: #3b82f6; stroke-width: 2.5; } .extension { fill: #f2f9e8; stroke: #76b900; stroke-width: 2.5; } .dark { fill: #1f2937; stroke: #111827; stroke-width: 2; } .line { fill: none; stroke: #334155; stroke-width: 2.5; marker-end: url(#arrow); } - .provision { fill: none; stroke: #334155; stroke-width: 2.5; stroke-dasharray: 8 7; marker-end: url(#arrow); } .flow { fill: none; stroke: #579000; stroke-width: 3; marker-end: url(#arrow-green); } - - - GATEWAY (CONTROL PLANE) - EXTERNAL SERVICES - OPENSHELL RUNTIME (DATA PLANE) - - - - - - - - API Server - auth · state · lifecycle - - - EXTENSION POINT - Gateway interceptors - modify · validate · observe - - - EXTENSION POINT - Credential driver - stores secret handles - - - EXTENSION POINT - Compute driver - places sandboxes - - - Credential store - - - - - - - - - Services and models - APIs · tools · inference - - - - - - Supervisor - policy · credentials - network mediation - - - EXTENSION POINT - Middleware - inspect · transform · deny - - - EXTENSION POINT - Isolation backend - controls the workload - - - SANDBOX BOUNDARY - - Agent - workload - - - - - - - - PROVISION - - - - Core component - - Extension point - - Workload - - Sandbox boundary - + + + DATA PLANE + + Agent + sandboxed workload + + EXTENSION POINT + Isolation backend + launch · exec · mediate + + Supervisor + policy · credentials + + EXTENSION POINT + Middleware + inspect · transform · deny + + Models, APIs + external services + + + + + + CONTROL PLANE + + You + CLI · SDK · TUI + + EXTENSION POINT + Interceptors + modify · validate · observe + + Gateway + auth · state · API + + EXTENSION POINT + Drivers + compute · credentials + + Infrastructure + runtimes · secret stores + + + +