openshell gateway

CLI reference for gateway lifecycle commands: start, stop, destroy, add, select, login, and info. Includes openshell status and openshell completions.

openshell gateway

Alias: gw

Manage the OpenShell gateway — deploy, stop, register, and select gateways.

---

Gateway selection

Every command that communicates with a gateway resolves the target through the following priority chain:

1. --gateway-endpoint <URL> — connect directly by URL without metadata lookup.
2. -g <NAME> / --gateway <NAME> — use a named gateway from stored metadata.
3. OPENSHELL_GATEWAY environment variable.
4. Active gateway from ~/.config/openshell/active_gateway.

--gateway-endpoint and --gateway / -g are global flags accepted by all commands, not just gateway subcommands.

The following global flags are accepted by all openshell commands:

Flag	Description
-g, --gateway NAME	Gateway name to operate on. Also read from OPENSHELL_GATEWAY.
--gateway-endpoint URL	Gateway endpoint URL. Connects directly without metadata lookup. Also read from OPENSHELL_GATEWAY_ENDPOINT.
-v, -vv, -vvv	Increase verbosity. -v = info, -vv = debug, -vvv = trace.
-h, --help	Print help.
-V, --version	Print version.

---

openshell gateway start

Deploy (or start) a gateway. Provisions a K3s cluster inside a Docker container locally, or over SSH for remote hosts.

openshell gateway start [OPTIONS]

--name · string · default: "openshell"

Gateway name. Also read from OPENSHELL_GATEWAY.

--port · integer · default: "8080"

Host port to map to the gateway.

--remote · string

SSH destination for remote deployment (e.g., user@hostname). Deploys the gateway container on the remote host over SSH.

--ssh-key · string

Path to SSH private key for remote deployment.

--gpu · boolean

Enable NVIDIA GPU passthrough. Passes all host GPUs into the cluster container and deploys the NVIDIA k8s-device-plugin. Requires NVIDIA drivers and the NVIDIA Container Toolkit on the host.

--gateway-host · string

Override the gateway host written into cluster metadata. By default, local clusters advertise 127.0.0.1. Set this when the client cannot reach the Docker host at 127.0.0.1 — for example in CI containers, WSL, or when Docker runs on a remote host. Common values: host.docker.internal, a LAN IP, or a hostname.

--recreate · boolean

Destroy and recreate the gateway from scratch if one already exists. Without this flag, an interactive prompt asks whether to recreate; in non-interactive mode the existing gateway is reused silently.

--plaintext · boolean

Listen on plaintext HTTP instead of mTLS. Use when the gateway sits behind a reverse proxy (e.g., Cloudflare Tunnel) that terminates TLS at the edge.

--disable-gateway-auth · boolean

Disable mTLS client certificate requirement. The server still listens on TLS, but clients are not required to present a certificate. Use when a reverse proxy cannot forward client certificates. Ignored when --plaintext is set.

--registry-username · string

Username for authenticating with the container image registry. Also read from OPENSHELL_REGISTRY_USERNAME. Defaults to __token__ when --registry-token is set.

--registry-token · string

Authentication token for pulling container images from the registry. For GHCR, this is a GitHub PAT with read:packages scope. Also read from OPENSHELL_REGISTRY_TOKEN.

Examples

# Start a local gateway on the default port
openshell gateway start

# Start a named gateway on a custom port
openshell gateway start --name my-gateway --port 9090

# Deploy on a remote host over SSH
openshell gateway start --remote user@10.0.0.5

# Start a GPU-enabled gateway
openshell gateway start --gpu

# Recreate an existing gateway
openshell gateway start --recreate

---

openshell gateway stop

Stop the gateway container, preserving cluster state. The gateway can be restarted later.

openshell gateway stop [OPTIONS]

--name · string

Gateway name. Defaults to the active gateway. Also read from OPENSHELL_GATEWAY.

--remote · string

Override SSH destination (auto-resolved from gateway metadata for remote gateways).

--ssh-key · string

Path to SSH private key for remote gateway.

---

openshell gateway destroy

Destroy the gateway and all its state (containers, volumes, cluster data). This is irreversible.

openshell gateway destroy [OPTIONS]

--name · string

Gateway name. Defaults to the active gateway. Also read from OPENSHELL_GATEWAY.

--remote · string

Override SSH destination (auto-resolved from gateway metadata for remote gateways).

--ssh-key · string

Path to SSH private key for remote gateway.

---

openshell gateway add

Register an existing gateway endpoint so it appears in openshell gateway select.

openshell gateway add ENDPOINT [OPTIONS]

ENDPOINT · string · required

Gateway endpoint URL (e.g., https://10.0.0.5:8080) or an ssh:// shorthand (e.g., ssh://user@host:8080).

--name · string

Gateway name. Auto-derived from the endpoint hostname when omitted.

--remote · string

Register a remote mTLS gateway accessible over SSH. The CLI extracts mTLS certificates from the running container automatically. Conflicts with --local.

--ssh-key · string

SSH private key for the remote host. Used with --remote or ssh:// endpoints.

--local · boolean

Register a local mTLS gateway running in Docker on this machine. The CLI extracts mTLS certificates automatically. Conflicts with --remote.

Without --remote or --local, the gateway is treated as an edge-authenticated (cloud) gateway: a browser is opened for authentication.

Examples

# Register a cloud (edge-auth) gateway
openshell gateway add https://gateway.example.com

# Register a remote mTLS gateway over SSH
openshell gateway add https://10.0.0.5:8080 --remote user@10.0.0.5

# Register a local Docker gateway
openshell gateway add https://127.0.0.1:8080 --local

# SSH shorthand (equivalent to --remote user@host)
openshell gateway add ssh://user@host:8080

---

openshell gateway select

Set the active gateway. When called without a name, opens an interactive chooser (on a TTY) or lists available gateways (non-interactive mode).

openshell gateway select [NAME]

NAME · string

Gateway name to activate. Omit to choose interactively or list in non-interactive mode.

Examples

# Interactive chooser
openshell gateway select

# Set a specific gateway as active
openshell gateway select my-gateway

---

openshell gateway login

Authenticate with an edge-authenticated gateway. Opens a browser for the edge proxy’s login flow and stores the token locally. Use this to re-authenticate when a token expires.

openshell gateway login [NAME]

NAME · string

Gateway name. Defaults to the active gateway.

---

openshell gateway info

Show deployment details for a gateway (endpoint, auth mode, port, remote host).

openshell gateway info [OPTIONS]

--name · string

Gateway name. Defaults to the active gateway. Also read from OPENSHELL_GATEWAY.

---

Authentication modes

Gateways use one of three authentication modes depending on how they were deployed:

Mode	When used	How credentials are stored
mTLS	Local and remote Docker deployments (gateway start, gateway add --local/--remote)	PEM files in ~/.config/openshell/gateways/<name>/mtls/
Edge JWT	Cloud gateways behind a reverse proxy (gateway add <url>)	Token in ~/.config/openshell/gateways/<name>/edge_token
Plaintext	Gateways deployed with --plaintext	None

See Gateway Authentication for the full connection flow.

---

openshell status

Show gateway status and health information for the active gateway.

openshell status

Use this to verify the gateway is reachable and healthy after deployment. No flags are required — the active gateway is resolved automatically.

---

openshell completions

Generate shell completion scripts for the OpenShell CLI.

openshell completions SHELL

SHELL · string · required

Shell to generate completions for. Valid values: bash, fish, zsh, powershell.

The script is output to stdout. Redirect it to the appropriate location for your shell:

Bash

mkdir -p ~/.local/share/bash-completion/completions
openshell completions bash > ~/.local/share/bash-completion/completions/openshell

On macOS with Homebrew (requires bash-completion):

openshell completions bash > $(brew --prefix)/etc/bash_completion.d/openshell.bash-completion

Fish

mkdir -p ~/.config/fish/completions
openshell completions fish > ~/.config/fish/completions/openshell.fish

Zsh

mkdir -p ~/.zfunc
openshell completions zsh > ~/.zfunc/_openshell

Add the following to your .zshrc before compinit:

fpath+=~/.zfunc

PowerShell

openshell completions powershell >> $PROFILE

If no profile exists yet, create one first:

New-Item -Path $PROFILE -Type File -Force