Deploy and Manage Gateways #

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

The gateway is responsible for:

Provisioning and managing sandboxes, including creation, deletion, and status monitoring.
Storing provider credentials (API keys, tokens) and delivering them to sandboxes at startup.
Delivering network and filesystem policies to sandboxes. Policy enforcement itself happens inside each sandbox through the proxy, OPA, Landlock, and seccomp.
Managing inference configuration and serving inference bundles so sandboxes can route requests to the correct backend.
Providing the SSH tunnel endpoint so you can connect to sandboxes without exposing them directly.

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

Deploy a Local Gateway #

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

$ openshell gateway start

Copy to clipboard

The gateway becomes reachable at https://127.0.0.1:8080. Verify it is healthy:

$ openshell status

Copy to clipboard

Tip

You do not need to deploy a gateway manually. If you run openshell sandbox create without a gateway, the CLI auto-bootstraps a local gateway for you.

To use a different port or name:

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

Copy to clipboard

Deploy a Remote Gateway #

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

$ openshell gateway start --remote user@hostname

Copy to clipboard

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

To specify an SSH key:

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

Copy to clipboard

Note

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

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

Copy to clipboard

Register an Existing Gateway #

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

Cloud Gateway #

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

Copy to clipboard

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 instead of deriving it from the hostname, use --name:

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

Copy to clipboard

If the token expires later, re-authenticate with:

$ openshell gateway login

Copy to clipboard

Remote Gateway #

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

Copy to clipboard

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

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

Copy to clipboard

Local Gateway #

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

Copy to clipboard

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:

$ openshell gateway select

Copy to clipboard

Switch the active gateway:

$ openshell gateway select my-remote-cluster

Copy to clipboard

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

$ openshell status -g my-other-cluster

Copy to clipboard

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

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

Copy to clipboard

Advanced Start Options #

Flag	Purpose
`--gpu`	Enable NVIDIA GPU passthrough. Requires NVIDIA drivers and the Container Toolkit on the host. OpenShell auto-selects CDI when enabled on the daemon and falls back to Docker’s NVIDIA GPU request path (`--gpus all`) otherwise.
`--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. Only needed for private registries. Also configurable with `OPENSHELL_REGISTRY_USERNAME`.
`--registry-token`	Authentication token for pulling container images. For GHCR, a GitHub PAT with `read:packages` scope. Only needed for private registries. Also configurable with `OPENSHELL_REGISTRY_TOKEN`.

Stop and Destroy #

Stop a gateway while preserving its state for later restart:

$ openshell gateway stop

Copy to clipboard

Permanently destroy a gateway and all its state:

$ openshell gateway destroy

Copy to clipboard

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

Target a specific gateway with --name:

$ openshell gateway stop --name my-gateway
$ openshell gateway destroy --name my-gateway

Copy to clipboard

Troubleshoot #

Check gateway health:

$ openshell status

Copy to clipboard

View gateway logs:

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

Copy to clipboard

Run a command inside the gateway container for deeper inspection:

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

Copy to clipboard

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

$ openshell gateway start --recreate

Copy to clipboard

Next Steps #

To create a sandbox using the gateway, refer to Manage Sandboxes.
To install the CLI and get started quickly, refer to the Quickstart.

Deploy and Manage Gateways #

Deploy a Local Gateway #

Deploy a Remote Gateway #

Register an Existing Gateway #

Cloud Gateway #

Remote Gateway #

Local Gateway #

Manage Multiple Gateways #

Advanced Start Options #

Stop and Destroy #

Troubleshoot #

Next Steps #

Related Articles