Documentation Index
Fetch the complete documentation index at: https://mintlify.com/NVIDIA/OpenShell/llms.txt
Use this file to discover all available pages before exploring further.
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:--gateway-endpoint <URL>— connect directly by URL without metadata lookup.-g <NAME>/--gateway <NAME>— use a named gateway from stored metadata.OPENSHELL_GATEWAYenvironment variable.- Active gateway from
~/.config/openshell/active_gateway.
--gateway-endpoint and --gateway / -g are global flags accepted by all commands, not just gateway subcommands.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.Gateway name. Also read from
OPENSHELL_GATEWAY.Host port to map to the gateway.
SSH destination for remote deployment (e.g.,
user@hostname). Deploys the gateway container on the remote host over SSH.Path to SSH private key for remote deployment.
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.
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.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.
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 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.Username for authenticating with the container image registry. Also read from
OPENSHELL_REGISTRY_USERNAME. Defaults to __token__ when --registry-token is set.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
openshell gateway stop
Stop the gateway container, preserving cluster state. The gateway can be restarted later.Gateway name. Defaults to the active gateway. Also read from
OPENSHELL_GATEWAY.Override SSH destination (auto-resolved from gateway metadata for remote gateways).
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.Gateway name. Defaults to the active gateway. Also read from
OPENSHELL_GATEWAY.Override SSH destination (auto-resolved from gateway metadata for remote gateways).
Path to SSH private key for remote gateway.
openshell gateway add
Register an existing gateway endpoint so it appears inopenshell gateway select.
Gateway endpoint URL (e.g.,
https://10.0.0.5:8080) or an ssh:// shorthand (e.g., ssh://user@host:8080).Gateway name. Auto-derived from the endpoint hostname when omitted.
Register a remote mTLS gateway accessible over SSH. The CLI extracts mTLS certificates from the running container automatically. Conflicts with
--local.SSH private key for the remote host. Used with
--remote or ssh:// endpoints.Register a local mTLS gateway running in Docker on this machine. The CLI extracts mTLS certificates automatically. Conflicts with
--remote.--remote or --local, the gateway is treated as an edge-authenticated (cloud) gateway: a browser is opened for authentication.
Examples
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).Gateway name to activate. Omit to choose interactively or list in non-interactive mode.
Examples
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.Gateway name. Defaults to the active gateway.
openshell gateway info
Show deployment details for a gateway (endpoint, auth mode, port, remote host).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 |
openshell status
Show gateway status and health information for the active gateway.openshell completions
Generate shell completion scripts for the OpenShell CLI.Shell to generate completions for. Valid values:
bash, fish, zsh, powershell.- Bash
- Fish
- Zsh
- PowerShell
bash-completion):