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

# Gateway Authentication

> Gateway resolution priority chain, authentication modes, connection flow, and credential file layout.

# Gateway authentication

This page describes how the CLI resolves a gateway, authenticates with it, and where credentials are stored. For how to deploy or register gateways, see [Gateways](/sandboxes/gateways).

## Gateway resolution

When any CLI command needs to talk to the gateway, it resolves the target through the following priority chain:

| Priority | Source                                    | Format                    |
| -------- | ----------------------------------------- | ------------------------- |
| 1        | `--gateway-endpoint <URL>` flag           | Direct endpoint URL       |
| 2        | `-g <NAME>` flag                          | Gateway name              |
| 3        | `OPENSHELL_GATEWAY` environment variable  | Gateway name              |
| 4        | `~/.config/openshell/active_gateway` file | Gateway name (plain text) |

Once the gateway name or URL is resolved, the CLI loads gateway metadata from disk to determine the endpoint URL and authentication mode.

## Authentication modes

The CLI uses one of three connection modes depending on the gateway's authentication configuration.

### mTLS

The default mode for self-deployed gateways. When you run `gateway start` or `gateway add --local` / `gateway add --remote`, the CLI extracts mTLS certificates from the running container and stores them locally. Every subsequent request presents a client certificate to prove identity.

The CLI loads three PEM files from `~/.config/openshell/gateways/<name>/mtls/`:

| File      | Purpose                                                       |
| --------- | ------------------------------------------------------------- |
| `ca.crt`  | CA certificate. Verifies the gateway's server certificate.    |
| `tls.crt` | Client certificate. Proves the CLI's identity to the gateway. |
| `tls.key` | Client private key.                                           |

**Connection flow:**

<Steps>
  <Step title="Load certificates">
    The CLI loads `ca.crt`, `tls.crt`, and `tls.key` from the gateway's `mtls/` directory.
  </Step>

  <Step title="Open TCP connection">
    A TCP connection is opened to the gateway endpoint.
  </Step>

  <Step title="TLS handshake">
    The CLI performs a TLS handshake, presenting the client certificate.
  </Step>

  <Step title="Gateway verification">
    The gateway verifies the client certificate against its CA.
  </Step>

  <Step title="HTTP/2 channel established">
    An HTTP/2 channel is established. All CLI commands use this channel.
  </Step>
</Steps>

### Edge JWT

For gateways behind a reverse proxy that handles authentication (for example, Cloudflare Access), the CLI uses a browser-based login flow and routes traffic through a WebSocket tunnel.

**Registration flow** (`openshell gateway add https://gateway.example.com`):

<Steps>
  <Step title="Store gateway metadata">
    The CLI stores gateway metadata with the edge authentication mode.
  </Step>

  <Step title="Open browser">
    Your browser opens to the gateway's authentication endpoint.
  </Step>

  <Step title="Reverse proxy login">
    The reverse proxy handles login (SSO, identity provider, etc.).
  </Step>

  <Step title="Token relay">
    After authentication, the browser relays the authorization token back to the CLI via a localhost callback.
  </Step>

  <Step title="Token stored">
    The CLI stores the token and sets the gateway as active.
  </Step>
</Steps>

**Connection flow** (subsequent commands):

<Steps>
  <Step title="Local proxy starts">
    The CLI starts a local proxy that listens on an ephemeral port.
  </Step>

  <Step title="WebSocket connection">
    The proxy opens a WebSocket connection (`wss://`) to the gateway, attaching the stored bearer token in the upgrade headers.
  </Step>

  <Step title="Proxy authenticates upgrade">
    The reverse proxy authenticates the WebSocket upgrade request.
  </Step>

  <Step title="Gateway bridges connection">
    The gateway bridges the WebSocket into the same service that handles direct mTLS connections.
  </Step>

  <Step title="Commands flow through tunnel">
    CLI commands send requests through the local proxy as plaintext HTTP/2 over the tunnel.
  </Step>
</Steps>

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

If the token expires, run `openshell gateway login` to open the browser flow again and update the stored token.

### Plaintext

When a gateway is deployed with `--plaintext`, TLS is disabled entirely. The CLI connects over plain HTTP/2.

<Warning>
  Plaintext mode is intended only for gateways behind a trusted reverse proxy or tunnel that handles TLS termination externally. Do not use this mode for gateways exposed directly to untrusted networks.
</Warning>

## Credential file layout

All gateway credentials and metadata are stored under `~/.config/openshell/`:

```
openshell/
  active_gateway                    # Plain text: active gateway name
  gateways/
    <name>/
      metadata.json                 # Gateway metadata (endpoint, auth mode, type)
      mtls/                         # mTLS bundle (local and remote gateways)
        ca.crt                      # CA certificate
        tls.crt                     # Client certificate
        tls.key                     # Client private key
      edge_token                    # Edge auth JWT (cloud gateways)
      last_sandbox                  # Last-used sandbox for this gateway
```

<CardGroup cols={2}>
  <Card title="Policy schema" icon="file-code" href="/reference/policy-schema">
    Complete field reference for the sandbox policy YAML.
  </Card>

  <Card title="Support matrix" icon="table" href="/reference/support-matrix">
    Supported platforms, prerequisites, and kernel requirements.
  </Card>
</CardGroup>