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

# Gateways

> Deploy local and remote gateways, register cloud gateways, and manage multiple gateway environments.

The gateway is the control plane for OpenShell. All control-plane traffic between the CLI and running sandboxes flows through it.

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. Enforcement happens inside each sandbox through the proxy, OPA, Landlock, and seccomp.
* Managing inference configuration and serving inference bundles.
* Providing the SSH tunnel endpoint so you can connect to sandboxes without exposing them directly.

The gateway runs inside a Docker container (no separate Kubernetes installation required) and exposes a single port with gRPC and HTTP multiplexed, secured by mTLS by default. It can be deployed locally, on a remote host via SSH, or behind a cloud reverse proxy.

<Tip>
  You do not need to deploy a gateway manually. Running `openshell sandbox create` without a gateway auto-bootstraps a local one for you.
</Tip>

## Deploy a local gateway

<Steps>
  <Step title="Start the gateway">
    Deploy a gateway on your workstation. The only prerequisite is a running Docker daemon.

    ```bash theme={null}
    openshell gateway start
    ```

    The gateway becomes reachable at `https://127.0.0.1:8080`.
  </Step>

  <Step title="Verify gateway health">
    ```bash theme={null}
    openshell status
    ```
  </Step>
</Steps>

To use a different port or name:

```bash theme={null}
openshell gateway start --port 9090
openshell gateway start --name dev-local
```

## Deploy a remote gateway

Deploy a gateway on a remote machine accessible via SSH. The only dependency on the remote host is Docker.

<Steps>
  <Step title="Start the remote gateway">
    ```bash theme={null}
    openshell gateway start --remote user@hostname
    ```

    The gateway is reachable at `https://<hostname>:8080`.
  </Step>

  <Step title="Specify an SSH key (optional)">
    ```bash theme={null}
    openshell gateway start --remote user@hostname --ssh-key ~/.ssh/my_key
    ```
  </Step>
</Steps>

<Note>
  For DGX Spark, use your Spark's mDNS hostname:

  ```bash theme={null}
  openshell gateway start --remote <username>@<spark-ssid>.local
  ```
</Note>

## Register an existing gateway

Use `openshell gateway add` to register a gateway that is already running.

<Tabs>
  <Tab title="Cloud gateway">
    Register a gateway behind a reverse proxy such as Cloudflare Access:

    ```bash theme={null}
    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 give the gateway a specific name:

    ```bash theme={null}
    openshell gateway add https://gateway.example.com --name production
    ```

    If the token expires later, re-authenticate with:

    ```bash theme={null}
    openshell gateway login
    ```
  </Tab>

  <Tab title="Remote gateway">
    Register a gateway on a remote host you have SSH access to:

    ```bash theme={null}
    openshell gateway add https://remote-host:8080 --remote user@remote-host
    ```

    Or use the `ssh://` scheme to combine the SSH destination and gateway port:

    ```bash theme={null}
    openshell gateway add ssh://user@remote-host:8080
    ```
  </Tab>

  <Tab title="Local gateway">
    Register a gateway running locally that was started outside the CLI:

    ```bash theme={null}
    openshell gateway add https://127.0.0.1:8080 --local
    ```
  </Tab>
</Tabs>

## Authentication

| Gateway type | Auth mechanism                                      |
| ------------ | --------------------------------------------------- |
| Local        | mTLS — client certificate issued by the gateway PKI |
| Remote (SSH) | mTLS over SSH tunnel                                |
| Cloud        | Browser-based login flow; CLI stores a bearer token |

For cloud gateways, use `--plaintext` and `--disable-gateway-auth` when deploying behind a TLS-terminating reverse proxy that cannot forward client certificates.

## Manage multiple gateways

One gateway is always the active gateway. All CLI commands target it by default. Both `gateway start` and `gateway add` automatically set the new gateway as active.

List all registered gateways and select the active one interactively:

```bash theme={null}
openshell gateway select
```

Switch to a specific gateway:

```bash theme={null}
openshell gateway select my-remote-cluster
```

Override the active gateway for a single command with `-g`:

```bash theme={null}
openshell status -g my-other-cluster
```

Show deployment details for a gateway, including endpoint, auth mode, and port:

```bash theme={null}
openshell gateway info
openshell gateway info --name my-remote-cluster
```

## Advanced start options

| Flag                     | Purpose                                                                                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--gpu`                  | Enable NVIDIA GPU passthrough. Requires NVIDIA drivers and the Container Toolkit on the host.                                                            |
| `--plaintext`            | Listen on HTTP instead of mTLS. Use behind a TLS-terminating reverse proxy.                                                                              |
| `--disable-gateway-auth` | Skip mTLS client certificate checks. Use when a reverse proxy cannot forward client certs.                                                               |
| `--registry-username`    | Username for registry authentication. Defaults to `__token__` when `--registry-token` is set. Also configurable with `OPENSHELL_REGISTRY_USERNAME`.      |
| `--registry-token`       | Authentication token for pulling container images. For GHCR, a GitHub PAT with `read:packages` scope. Also configurable with `OPENSHELL_REGISTRY_TOKEN`. |

## Stop and destroy

<CodeGroup>
  ```bash Stop (preserves state) theme={null}
  openshell gateway stop
  openshell gateway stop --name my-gateway
  ```

  ```bash Destroy (permanent) theme={null}
  openshell gateway destroy
  openshell gateway destroy --name my-gateway
  ```
</CodeGroup>

<Note>
  For cloud gateways, `gateway destroy` removes only the local registration. It does not affect the remote deployment.
</Note>

## Troubleshoot

Check gateway health:

```bash theme={null}
openshell status
```

View gateway logs:

```bash theme={null}
openshell doctor logs
openshell doctor logs --tail        # stream live
openshell doctor logs --lines 50    # last 50 lines
```

Run a command inside the gateway container for deeper inspection:

```bash theme={null}
openshell doctor exec -- kubectl get pods -A
openshell doctor exec -- sh
```

If the gateway is in a bad state, recreate it:

```bash theme={null}
openshell gateway start --recreate
```

## Next steps

<CardGroup cols={2}>
  <Card title="Manage sandboxes" icon="box" href="/sandboxes/manage-sandboxes">
    Create sandboxes, connect to them, and manage their lifecycle.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install the CLI and run your first sandbox end to end.
  </Card>
</CardGroup>