Skip to main content

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

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.

​
Gateway resolution

When any CLI command needs to talk to the gateway, it resolves the target through the following priority chain:
PrioritySourceFormat
1--gateway-endpoint <URL> flagDirect endpoint URL
2-g <NAME> flagGateway name
3OPENSHELL_GATEWAY environment variableGateway name
4~/.config/openshell/active_gateway fileGateway 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/:
FilePurpose
ca.crtCA certificate. Verifies the gateway’s server certificate.
tls.crtClient certificate. Proves the CLI’s identity to the gateway.
tls.keyClient private key.
Connection flow:
1

Load certificates

The CLI loads ca.crt, tls.crt, and tls.key from the gateway’s mtls/ directory.
2

Open TCP connection

A TCP connection is opened to the gateway endpoint.
3

TLS handshake

The CLI performs a TLS handshake, presenting the client certificate.
4

Gateway verification

The gateway verifies the client certificate against its CA.
5

HTTP/2 channel established

An HTTP/2 channel is established. All CLI commands use this channel.

​
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):
1

Store gateway metadata

The CLI stores gateway metadata with the edge authentication mode.
2

Open browser

Your browser opens to the gateway’s authentication endpoint.
3

Reverse proxy login

The reverse proxy handles login (SSO, identity provider, etc.).
4

Token relay

After authentication, the browser relays the authorization token back to the CLI via a localhost callback.
5

Token stored

The CLI stores the token and sets the gateway as active.
Connection flow (subsequent commands):
1

Local proxy starts

The CLI starts a local proxy that listens on an ephemeral port.
2

WebSocket connection

The proxy opens a WebSocket connection (wss://) to the gateway, attaching the stored bearer token in the upgrade headers.
3

Proxy authenticates upgrade

The reverse proxy authenticates the WebSocket upgrade request.
4

Gateway bridges connection

The gateway bridges the WebSocket into the same service that handles direct mTLS connections.
5

Commands flow through tunnel

CLI commands send requests through the local proxy as plaintext HTTP/2 over the tunnel.
This is transparent to the user. All CLI commands work the same regardless of whether the gateway uses mTLS or edge authentication.
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.
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.

​
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

Policy schema

Complete field reference for the sandbox policy YAML.

Support matrix

Supported platforms, prerequisites, and kernel requirements.

Build docs developers (and LLMs) love

Get started for freeTalk to us