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

OpenShell separates gateway access from the compute driver that runs sandboxes. Use Installation to install OpenShell, choose a compute driver, and start a gateway. This page covers working with gateway entries after a gateway exists.

Gateway Compute Drivers

A gateway provisions sandboxes through the compute driver configured for that gateway.

All compute drivers expose the same gateway API surface. Sandboxes, policies, and providers work the same after the CLI registers the gateway endpoint. The difference is how the gateway creates sandbox workloads and how operators expose the gateway to users.

Configure Service Forwarding

Sandbox service routing is enabled for gateways by default. Users expose long-running sandbox services with openshell service expose, and the gateway routes browser traffic from the printed service URL to the loopback port inside the sandbox.

Loopback gateways use openshell.localhost service URLs. OpenShell prints a URL in the form http://<sandbox>.openshell.localhost:<port>/ or http://<sandbox>--<service>.openshell.localhost:<port>/ when a service name is provided.

Browser traffic enters the same gateway listener as mTLS-protected gRPC, but plaintext HTTP is accepted only from loopback clients and only for sandbox service hostnames. Gateway APIs, auth routes, health endpoints, and non-service hostnames remain unavailable over plaintext HTTP. Cross-origin and sibling-subdomain browser requests are rejected before reaching the sandbox service.

Disable the local browser path with --enable-loopback-service-http=false or OPENSHELL_ENABLE_LOOPBACK_SERVICE_HTTP=false.

Custom HTTPS service domains use the gateway server SAN configuration. Add a wildcard DNS SAN such as *.apps.example.com to the gateway certificate and pass the same SAN to the gateway with --server-san or OPENSHELL_SERVER_SAN.

For remote or non-loopback gateways, browser service URLs remain HTTPS and require normal gateway authentication.

Register an Existing Gateway

Use openshell gateway add to register any reachable gateway endpoint so the CLI can target it.

Register a plaintext local endpoint, such as a trusted port-forward:

$
openshell gateway add http://127.0.0.1:8080 --local --name local

Register a gateway behind an authenticated reverse proxy:

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

This opens your browser for the proxy’s login flow when the gateway uses edge authentication. If the token expires later, re-authenticate with:

$
openshell gateway login production

For direct mTLS endpoints, place the CLI client certificate bundle in the gateway credential directory described in Gateway Authentication, then register or select that gateway name.

Manage Multiple Gateways

One gateway is always the active gateway. All CLI commands target it by default. gateway add sets the new gateway as active.

The active gateway is the persisted default. The -g flag and the OPENSHELL_GATEWAY environment variable override it when commands resolve a gateway. If OPENSHELL_GATEWAY is set to a different gateway, openshell gateway select <name> still saves the new default and warns that the current shell continues to use the environment value until you unset or update it.

List all registered gateways:

$
openshell gateway list

Switch the active gateway:

$
openshell gateway select production

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

$
openshell status -g staging

Inspect Gateway Status

Use openshell status for a quick health check:

$
openshell status

Use openshell gateway info when you need the registered endpoint, gateway metadata, or compute driver details:

$
openshell gateway info
$
openshell gateway info --name production

Remove a local CLI registration without stopping the gateway service:

$
openshell gateway remove production

Troubleshoot

Check gateway health:

$
openshell status
$
openshell gateway info

For Docker-backed local gateways, inspect Docker and the gateway process or container started by your local workflow:

$
openshell doctor check
$
openshell gateway info

For Kubernetes gateways, inspect the gateway workload and cluster events:

$
kubectl -n openshell get pods
$
kubectl -n openshell logs statefulset/openshell
$
kubectl -n openshell get events --sort-by=.lastTimestamp

For Podman or MicroVM gateways managed by systemd, inspect the user service and logs:

$
systemctl --user status openshell-gateway
$
journalctl --user -u openshell-gateway --no-pager -n 50

For sandbox startup failures, inspect the selected compute driver:

Next Steps

• To install OpenShell and choose a compute driver, refer to Installation.
• To create a sandbox using the gateway, refer to Manage Sandboxes.