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

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

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

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.

```bash theme={null}
openshell gateway start [OPTIONS]
```

<ParamField body="--name" type="string" default="openshell">
  Gateway name. Also read from `OPENSHELL_GATEWAY`.
</ParamField>

<ParamField body="--port" type="integer" default="8080">
  Host port to map to the gateway.
</ParamField>

<ParamField body="--remote" type="string">
  SSH destination for remote deployment (e.g., `user@hostname`). Deploys the gateway container on the remote host over SSH.
</ParamField>

<ParamField body="--ssh-key" type="string">
  Path to SSH private key for remote deployment.
</ParamField>

<ParamField body="--gpu" type="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.
</ParamField>

<ParamField body="--gateway-host" type="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.
</ParamField>

<ParamField body="--recreate" type="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.
</ParamField>

<ParamField body="--plaintext" type="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.
</ParamField>

<ParamField body="--disable-gateway-auth" type="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.
</ParamField>

<ParamField body="--registry-username" type="string">
  Username for authenticating with the container image registry. Also read from `OPENSHELL_REGISTRY_USERNAME`. Defaults to `__token__` when `--registry-token` is set.
</ParamField>

<ParamField body="--registry-token" type="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`.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
openshell gateway stop [OPTIONS]
```

<ParamField body="--name" type="string">
  Gateway name. Defaults to the active gateway. Also read from `OPENSHELL_GATEWAY`.
</ParamField>

<ParamField body="--remote" type="string">
  Override SSH destination (auto-resolved from gateway metadata for remote gateways).
</ParamField>

<ParamField body="--ssh-key" type="string">
  Path to SSH private key for remote gateway.
</ParamField>

***

## openshell gateway destroy

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

```bash theme={null}
openshell gateway destroy [OPTIONS]
```

<ParamField body="--name" type="string">
  Gateway name. Defaults to the active gateway. Also read from `OPENSHELL_GATEWAY`.
</ParamField>

<ParamField body="--remote" type="string">
  Override SSH destination (auto-resolved from gateway metadata for remote gateways).
</ParamField>

<ParamField body="--ssh-key" type="string">
  Path to SSH private key for remote gateway.
</ParamField>

***

## openshell gateway add

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

```bash theme={null}
openshell gateway add ENDPOINT [OPTIONS]
```

<ParamField body="ENDPOINT" type="string" required>
  Gateway endpoint URL (e.g., `https://10.0.0.5:8080`) or an `ssh://` shorthand (e.g., `ssh://user@host:8080`).
</ParamField>

<ParamField body="--name" type="string">
  Gateway name. Auto-derived from the endpoint hostname when omitted.
</ParamField>

<ParamField body="--remote" type="string">
  Register a remote mTLS gateway accessible over SSH. The CLI extracts mTLS certificates from the running container automatically. Conflicts with `--local`.
</ParamField>

<ParamField body="--ssh-key" type="string">
  SSH private key for the remote host. Used with `--remote` or `ssh://` endpoints.
</ParamField>

<ParamField body="--local" type="boolean">
  Register a local mTLS gateway running in Docker on this machine. The CLI extracts mTLS certificates automatically. Conflicts with `--remote`.
</ParamField>

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

### Examples

```bash theme={null}
# 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).

```bash theme={null}
openshell gateway select [NAME]
```

<ParamField body="NAME" type="string">
  Gateway name to activate. Omit to choose interactively or list in non-interactive mode.
</ParamField>

### Examples

```bash theme={null}
# 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.

```bash theme={null}
openshell gateway login [NAME]
```

<ParamField body="NAME" type="string">
  Gateway name. Defaults to the active gateway.
</ParamField>

***

## openshell gateway info

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

```bash theme={null}
openshell gateway info [OPTIONS]
```

<ParamField body="--name" type="string">
  Gateway name. Defaults to the active gateway. Also read from `OPENSHELL_GATEWAY`.
</ParamField>

***

## 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](/reference/gateway-auth) for the full connection flow.

***

## openshell status

Show gateway status and health information for the active gateway.

```bash theme={null}
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.

```bash theme={null}
openshell completions SHELL
```

<ParamField body="SHELL" type="string" required>
  Shell to generate completions for. Valid values: `bash`, `fish`, `zsh`, `powershell`.
</ParamField>

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

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    mkdir -p ~/.local/share/bash-completion/completions
    openshell completions bash > ~/.local/share/bash-completion/completions/openshell
    ```

    On macOS with Homebrew (requires `bash-completion`):

    ```bash theme={null}
    openshell completions bash > $(brew --prefix)/etc/bash_completion.d/openshell.bash-completion
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    mkdir -p ~/.config/fish/completions
    openshell completions fish > ~/.config/fish/completions/openshell.fish
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    mkdir -p ~/.zfunc
    openshell completions zsh > ~/.zfunc/_openshell
    ```

    Add the following to your `.zshrc` before `compinit`:

    ```bash theme={null}
    fpath+=~/.zfunc
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    openshell completions powershell >> $PROFILE
    ```

    If no profile exists yet, create one first:

    ```powershell theme={null}
    New-Item -Path $PROFILE -Type File -Force
    ```
  </Tab>
</Tabs>