Gateways

Deploy local and remote gateways, register cloud gateways, and manage multiple gateway environments.

The gateway is the control plane for OpenShell. All control-plane traffic between the CLI and running sandboxes flows through it.

The gateway is responsible for:

• Provisioning and managing sandboxes, including creation, deletion, and status monitoring.
• Storing provider credentials and delivering them to sandboxes at startup.
• Delivering network and filesystem policies to sandboxes. Enforcement happens inside each sandbox through the proxy, OPA, Landlock, and seccomp.
• Managing inference configuration and serving inference bundles.
• Providing the SSH tunnel endpoint so you can connect to sandboxes without exposing them directly.

The gateway runs inside a Docker container (no separate Kubernetes installation required) and exposes a single port with gRPC and HTTP multiplexed, secured by mTLS by default. It can be deployed locally, on a remote host via SSH, or behind a cloud reverse proxy.

You do not need to deploy a gateway manually. Running openshell sandbox create without a gateway auto-bootstraps a local one for you.

Deploy a local gateway

1. Start the gateway

   Deploy a gateway on your workstation. The only prerequisite is a running Docker daemon.

   openshell gateway start
   

   The gateway becomes reachable at https://127.0.0.1:8080.

2. Verify gateway health

   openshell status
   

To use a different port or name:

openshell gateway start --port 9090
openshell gateway start --name dev-local

Deploy a remote gateway

Deploy a gateway on a remote machine accessible via SSH. The only dependency on the remote host is Docker.

1. Start the remote gateway

   openshell gateway start --remote user@hostname
   

   The gateway is reachable at https://<hostname>:8080.

2. Specify an SSH key (optional)

   openshell gateway start --remote user@hostname --ssh-key ~/.ssh/my_key
   

For DGX Spark, use your Spark’s mDNS hostname:

openshell gateway start --remote <username>@<spark-ssid>.local

Register an existing gateway

Use openshell gateway add to register a gateway that is already running.

Cloud gateway

Register a gateway behind a reverse proxy such as Cloudflare Access:

openshell gateway add https://gateway.example.com

This opens your browser for the proxy’s login flow. After authentication, the CLI stores a bearer token and sets the gateway as active.

To give the gateway a specific name:

openshell gateway add https://gateway.example.com --name production

If the token expires later, re-authenticate with:

openshell gateway login

Remote gateway

Register a gateway on a remote host you have SSH access to:

openshell gateway add https://remote-host:8080 --remote user@remote-host

Or use the ssh:// scheme to combine the SSH destination and gateway port:

openshell gateway add ssh://user@remote-host:8080

Local gateway

Register a gateway running locally that was started outside the CLI:

openshell gateway add https://127.0.0.1:8080 --local

Authentication

Gateway type	Auth mechanism
Local	mTLS — client certificate issued by the gateway PKI
Remote (SSH)	mTLS over SSH tunnel
Cloud	Browser-based login flow; CLI stores a bearer token

For cloud gateways, use --plaintext and --disable-gateway-auth when deploying behind a TLS-terminating reverse proxy that cannot forward client certificates.

Manage multiple gateways

One gateway is always the active gateway. All CLI commands target it by default. Both gateway start and gateway add automatically set the new gateway as active.

List all registered gateways and select the active one interactively:

openshell gateway select

Switch to a specific gateway:

openshell gateway select my-remote-cluster

Override the active gateway for a single command with -g:

openshell status -g my-other-cluster

Show deployment details for a gateway, including endpoint, auth mode, and port:

openshell gateway info
openshell gateway info --name my-remote-cluster

Advanced start options

Flag	Purpose
--gpu	Enable NVIDIA GPU passthrough. Requires NVIDIA drivers and the Container Toolkit on the host.
--plaintext	Listen on HTTP instead of mTLS. Use behind a TLS-terminating reverse proxy.
--disable-gateway-auth	Skip mTLS client certificate checks. Use when a reverse proxy cannot forward client certs.
--registry-username	Username for registry authentication. Defaults to __token__ when --registry-token is set. Also configurable with OPENSHELL_REGISTRY_USERNAME.
--registry-token	Authentication token for pulling container images. For GHCR, a GitHub PAT with read:packages scope. Also configurable with OPENSHELL_REGISTRY_TOKEN.

Stop and destroy

Stop (preserves state)

openshell gateway stop
openshell gateway stop --name my-gateway

For cloud gateways, gateway destroy removes only the local registration. It does not affect the remote deployment.

Troubleshoot

Check gateway health:

openshell status

View gateway logs:

openshell doctor logs
openshell doctor logs --tail        # stream live
openshell doctor logs --lines 50    # last 50 lines

Run a command inside the gateway container for deeper inspection:

openshell doctor exec -- kubectl get pods -A
openshell doctor exec -- sh

If the gateway is in a bad state, recreate it:

openshell gateway start --recreate

Next steps

Manage sandboxes

Create sandboxes, connect to them, and manage their lifecycle.

Quickstart

Install the CLI and run your first sandbox end to end.