OpenShell/examples/gateway-deploy-connect.md

Deploying and Connecting to a Gateway

Deploy or register an OpenShell gateway, verify it is reachable, and run your first sandbox. This example covers Helm-managed Kubernetes gateways, existing gateway endpoints, and Cloudflare-fronted deployments.

Prerequisites

• OpenShell CLI installed (openshell)
• A reachable gateway endpoint, or access to a Kubernetes cluster where you can install the Helm chart
• For Kubernetes installs, a CNI that enforces ingress and egress NetworkPolicy in sandbox namespaces

Helm Deployment

Install the gateway into a Kubernetes cluster you manage:

kubectl create namespace openshell
helm upgrade --install openshell deploy/helm/openshell \
  --namespace openshell \
  --set server.disableTls=true \
  --set service.type=ClusterIP

For local evaluation, forward the service and register the forwarded endpoint:

kubectl -n openshell port-forward svc/openshell 8080:8080
openshell gateway add http://127.0.0.1:8080 --local --name local

Production deployments should keep TLS enabled or place the gateway behind a trusted TLS-terminating ingress, load balancer, or access proxy.

Existing Gateway Endpoint

Register a gateway that is already running:

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

Verify the gateway:

openshell status

Expected output:

Gateway: https://gateway.example.com
Status:  HEALTHY
Version: <version>

Create a Sandbox

openshell sandbox create --name hello -- echo "it works"
openshell sandbox connect hello

Clean up the sandbox when finished:

openshell sandbox delete hello

Edge-Authenticated Gateway

For gateways running behind a reverse proxy that handles authentication, such as Cloudflare Access, register the endpoint and authenticate via browser:

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 re-authenticate after token expiry:

openshell gateway login

How Edge-Authenticated Connections Differ

Reverse proxies that authenticate via browser-style GET requests are incompatible with gRPC's HTTP/2 POST transport. To work around this, the CLI uses a WebSocket tunnel:

1. The CLI starts a local proxy that listens on an ephemeral port.
2. gRPC traffic is sent as plaintext HTTP/2 to this local proxy.
3. The proxy opens a WebSocket (wss://) to the gateway's tunnel endpoint, attaching the bearer token in the upgrade headers.
4. The edge proxy authenticates the WebSocket upgrade request.
5. The gateway receives the WebSocket connection and pipes it into the same gRPC service that handles direct mTLS connections.

This is transparent to the user. CLI commands work the same regardless of whether the gateway uses mTLS or edge authentication.

Managing Multiple Gateways

List all registered gateways:

openshell gateway select

Switch the active gateway:

openshell gateway select production

Override the active gateway for a single command:

openshell status -g production

Troubleshooting

Check gateway registration details:

openshell gateway info
openshell status

For Helm deployments, inspect the release and gateway workload:

helm -n openshell status openshell
kubectl -n openshell get statefulset,pod,svc,pvc
kubectl -n openshell logs statefulset/openshell --tail=100