> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How OpenShell works — the four components, request flow, deployment modes, and the K3s cluster inside Docker.

OpenShell runs inside a Docker container. Each sandbox is an isolated environment managed through the gateway. Four components work together to keep agents secure.

## Components

The table below describes each component and its role in the system.

| Component          | Role                                                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gateway**        | Control-plane API that coordinates sandbox lifecycle and state, acts as the auth boundary, and brokers requests across the platform.                                                              |
| **Sandbox**        | Isolated runtime that includes container supervision and policy-enforced egress routing.                                                                                                          |
| **Policy Engine**  | Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. |
| **Privacy Router** | Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy.                                                                      |

## How a request flows

Every outbound connection from agent code passes through the same decision path.

<Steps>
  <Step title="Agent opens a connection">
    The agent process opens an outbound connection — an API call, package install, git clone, or any other network request.
  </Step>

  <Step title="Proxy intercepts">
    The proxy inside the sandbox intercepts the connection and identifies which binary opened it.
  </Step>

  <Step title="inference.local special handling">
    If the target is `https://inference.local`, the proxy handles it as managed inference before policy evaluation. OpenShell strips the sandbox-supplied credentials, injects the configured backend credentials, and forwards the request to the managed model endpoint.
  </Step>

  <Step title="Policy engine evaluates">
    For every other destination, the proxy queries the policy engine with the destination, port, and calling binary.
  </Step>

  <Step title="Allow or deny">
    The policy engine returns one of two decisions:

    * **Allow** — the destination and binary match a policy block. Traffic flows directly to the external service.
    * **Deny** — no policy block matched. The connection is blocked and logged.

    For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through.
  </Step>
</Steps>

## Deployment modes

OpenShell can run locally, on a remote host, or behind a cloud proxy. The architecture is identical in all cases — only the Docker container location and authentication mode change.

| Mode       | Description                                                                                                       | Command                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Local**  | The gateway runs inside Docker on your workstation. The CLI provisions it automatically on first use.             | `openshell gateway start`                           |
| **Remote** | The gateway runs on a remote host via SSH. Only Docker is required on the remote machine.                         | `openshell gateway start --remote user@host`        |
| **Cloud**  | A gateway already running behind a reverse proxy (e.g. Cloudflare Access). Register and authenticate via browser. | `openshell gateway add https://gateway.example.com` |

You can register multiple gateways and switch between them with `openshell gateway select`.

```bash theme={null}
# Start a local gateway
openshell gateway start

# Start a gateway on a remote host over SSH
openshell gateway start --remote user@host

# Register an existing cloud gateway
openshell gateway add https://gateway.example.com

# Switch between registered gateways
openshell gateway select
```

## K3s cluster inside Docker

All components — Gateway, Sandbox, Policy Engine, and Privacy Router — run as a [K3s](https://k3s.io/) Kubernetes cluster inside a single Docker container. No separate Kubernetes install is required. The `openshell gateway` commands take care of provisioning the container and the cluster.

The `openshell-bootstrap` crate handles cluster setup, image loading, and mTLS PKI generation on first start.

<Note>
  Because the cluster runs inside a single Docker container, OpenShell requires only Docker Desktop (or a Docker daemon) on the host machine — no Kubernetes knowledge needed to get started.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="box" href="/sandboxes/manage-sandboxes">
    Learn how OpenShell enforces isolation across all protection layers.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install the CLI and create your first sandbox.
  </Card>
</CardGroup>