Manage Gateways
Register OpenShell gateways, switch between environments, inspect gateway status, and troubleshoot gateway access.
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.
- Resolving endpoint-bound provider environments for the providers attached to each sandbox.
- 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 Runtimes
Section titled “Gateway Runtimes”A gateway provisions sandboxes through the compute driver configured for that gateway.
| Runtime | Where sandboxes run | Best for |
|---|---|---|
| Docker | Containers on the Docker daemon host. | Solo development, quick iteration, and single-machine gateways. |
| Podman | Rootless containers on the gateway host. | Workstations that avoid a rootful Docker daemon. |
| Kubernetes | Pods in an operator-managed cluster. | Shared clusters and cloud environments. |
| MicroVM | VM-backed sandboxes. | Workflows that need VM-backed isolation. |
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
Section titled “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://<workspace>--<sandbox>.openshell.localhost:<port>/, or http://<workspace>--<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.
When multiple gateways share one service domain behind a single ingress, each gateway can set service_hostname_format = "hashed" (--service-hostname-format hashed or [openshell.gateway].service_hostname_format). Service URLs then use an opaque fixed-length hashed label — https://<hash>.apps.example.com/ — derived from the gateway installation name, unique per gateway, instead of the readable composite hostname. See Configuration for the field, its validation, and the effects of changing it.
For remote or non-loopback gateways, browser service URLs remain HTTPS and require normal gateway authentication.
Register an Existing Gateway
Section titled “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 localRegister a gateway behind an authenticated reverse proxy:
openshell gateway add https://gateway.example.com --name productionThis 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 productionFor 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
Section titled “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.
Installers can seed read-only gateway entries for package-managed local services. By default the CLI reads these from /etc/openshell, using the same active_gateway plus gateways/<name>/metadata.json layout as per-user config. Packages can override that system config root with a non-empty absolute OPENSHELL_SYSTEM_GATEWAY_DIR when needed; empty or relative values fall back to /etc/openshell and log a warning. These entries appear in openshell gateway list and can be selected like user registrations. openshell gateway list and openshell term label each gateway as user or system so you can see which config layer owns it. openshell gateway remove removes only per-user registrations. Register a per-user gateway with the same name when you need to shadow an installer-provided default.
List all registered gateways. The table shows each gateway’s endpoint, type, config source, authentication mode, and remote target when a remote registration has one:
openshell gateway listUse structured output when you need the complete local registration metadata,
including remote_host and resolved_host for remote registrations:
openshell gateway list -o jsonSwitch the active gateway:
openshell gateway select productionOverride the active gateway for a single command with -g:
openshell status -g stagingInspect Gateway Status
Section titled “Inspect Gateway Status”Use openshell status for a live gateway check. It reports gateway
reachability, authentication, and the gateway version independently:
openshell statusStatus: Connected means the public health endpoint responded.
Authentication: Authenticated confirms the configured credentials also
passed the gateway authentication layer. If authentication fails while status
remains connected, run openshell gateway login <name> to refresh the stored
credentials.
For automation or scripting, use --output json or --output yaml to get machine-readable output:
openshell status --output jsonUse openshell gateway info when you need elevated runtime details such as
initialized compute drivers and driver-reported capability versions:
openshell gateway infoUse structured output when scripting against live runtime info:
openshell gateway info -o jsonRemove a local CLI registration without stopping the gateway service:
openshell gateway remove productionTroubleshoot
Section titled “Troubleshoot”Check gateway health:
openshell statusopenshell gateway infoFor Docker-backed local gateways, inspect Docker and the gateway process or container started by your local workflow:
openshell doctor checkopenshell gateway listFor Kubernetes gateways, inspect the gateway workload and cluster events:
kubectl -n openshell get deployment,statefulset,podskubectl -n openshell logs deployment/openshell -c openshell-gateway --tail=100kubectl -n openshell logs statefulset/openshell -c openshell-gateway --tail=100kubectl -n openshell get events --sort-by=.lastTimestampFor Podman or MicroVM gateways managed by systemd, inspect the user service and logs:
systemctl --user status openshell-gatewayjournalctl --user -u openshell-gateway --no-pager -n 50For sandbox startup failures, inspect the selected compute driver:
| Compute Driver | What to check |
|---|---|
| Docker | Docker daemon health, image availability, gateway logs, and sandbox container state. |
| Podman | Podman socket availability, rootless networking, image availability, and sandbox container state. |
| Kubernetes | Events and sandbox pods in the namespace configured by server.sandboxNamespace. |
| MicroVM | VM driver logs, rootfs availability, and gateway logs. |
Next Steps
Section titled “Next Steps”- To install OpenShell and choose a compute driver, refer to Installation.
- To configure workspace membership and roles, refer to Workspaces.
- To create a sandbox using the gateway, refer to Manage Sandboxes.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.