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.

1. Agent opens a connection

   The agent process opens an outbound connection — an API call, package install, git clone, or any other network request.

2. Proxy intercepts

   The proxy inside the sandbox intercepts the connection and identifies which binary opened it.

3. 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.

4. Policy engine evaluates

   For every other destination, the proxy queries the policy engine with the destination, port, and calling binary.

5. 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.

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.

# 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 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.

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.

Next steps

Sandboxes

Learn how OpenShell enforces isolation across all protection layers.

Quickstart

Install the CLI and create your first sandbox.