NVIDIA · miyoungc · May 4, 2026
@@ -22,7 +22,14 @@ The CLI loads gateway metadata from disk to determine the endpoint URL and authe
 
 ## Authentication Modes
 
-The CLI uses one of three connection modes depending on the gateway's authentication configuration.
+The CLI uses one of four connection modes depending on the gateway's authentication configuration.
+
+| `auth_mode` | Transport | Identity | Token storage |
+|---|---|---|---|
+| `mtls` | mTLS client cert | Cert CN | None |
+| `plaintext` | HTTP (no TLS) | None | None |
+| `cloudflare_jwt` | Edge TLS (Cloudflare Tunnel) | Cloudflare Access JWT | `edge_token` |
+| `oidc` | mTLS or plaintext | OIDC JWT | `oidc_token.json` |
 
 ### mTLS (local and remote gateways)
 
@@ -80,6 +87,73 @@ openshell gateway add http://127.0.0.1:8080 --local
 
 This stores the gateway with `auth_mode = plaintext`, skips mTLS certificate extraction, and does not open the browser login flow.
 
+### OIDC
+
+OIDC authentication validates a JSON Web Token bearer on every gRPC request against an external OpenID Connect provider. Use OIDC when you want centralized identity, role-based access control, or fine-grained scope enforcement on a shared gateway. The transport stays the same as the gateway's TLS configuration, so OIDC layers on top of mTLS, plaintext, or an edge-terminated TLS deployment.
+
+Register an OIDC gateway by passing the issuer URL:
+
+```shell
+openshell gateway add http://gateway.example.com:8080 \
+  --oidc-issuer https://keycloak.example.com/realms/openshell
+```
+
+The CLI fetches `/auth/oidc-config` on the gateway to discover the audience and remaining OIDC parameters, then stores `auth_mode = oidc` in metadata. Pass `--oidc-client-id` and `--oidc-audience` when the audience differs from the client ID, which is common with Microsoft Entra ID:
+
+```shell
+openshell gateway add http://gateway.example.com:8080 \
+  --oidc-issuer https://login.microsoftonline.com/{tenant-id}/v2.0 \
+  --oidc-client-id {client-id} \
+  --oidc-audience api://openshell
+```
+
+Authenticate interactively with the browser flow:
+
+```shell
+openshell gateway login
+```
+
+The CLI runs Authorization Code with PKCE against the issuer, stores the resulting access and refresh tokens in `oidc_token.json` with `0600` permissions, and silently refreshes the access token on subsequent commands. If a refresh fails, run `openshell gateway login` again to re-authenticate.
+
+For CI and other non-interactive environments, set `OPENSHELL_OIDC_CLIENT_SECRET` before running `openshell gateway login`. The CLI uses the Client Credentials grant instead of opening a browser.
+
+#### Server-side validation
+
+`openshell gateway start` exposes the matching server-side flags. The default values target Keycloak realms with `realm_access.roles`:
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--oidc-issuer` | (none) | OIDC issuer URL. Setting this enables JWT validation. |
+| `--oidc-audience` | `openshell-cli` | Expected `aud` claim. |
+| `--oidc-client-id` | `openshell-cli` | Client ID stored in gateway metadata for CLI login. |
+| `--oidc-roles-claim` | `realm_access.roles` | Dot-separated path to the roles claim in the JWT. |
+| `--oidc-admin-role` | `openshell-admin` | Role required for admin operations like provider mutation and global policy updates. |
+| `--oidc-user-role` | `openshell-user` | Role required for sandbox and read operations. |
+| `--oidc-scopes-claim` | (none) | Claim path for scopes. Setting this enables fine-grained scope enforcement on top of roles. |
+| `--oidc-scopes` | (none) | Scopes the CLI requests during login. Stored in gateway metadata. |
+
+Setting both `--oidc-admin-role` and `--oidc-user-role` to empty strings switches the gateway into authentication-only mode. Any token the issuer signs for the configured audience is accepted, regardless of role claims. This mode supports providers that do not emit roles in their JWTs (such as GitHub Actions OIDC). Combine it with `--oidc-scopes-claim` and a narrow audience to reduce the blast radius of a leaked token.
+
+#### Method classification
+
+The gateway classifies every gRPC method into one of three groups:
+
+- **Unauthenticated** — health probes and gRPC reflection accept requests without auth.
+- **Sandbox-secret** — the sandbox supervisor uses the SSH handshake secret to fetch its policy, push logs, and resolve inference routes. The supervisor never holds an OIDC token.
+- **Bearer or dual-auth** — CLI calls present `authorization: Bearer <jwt>`. The server validates the signature against the cached JWKS, checks `iss`, `aud`, and `exp`, then enforces the configured roles and scopes.
+
+For full method-to-role mapping, scope definitions, JWKS caching, and provider-specific examples, refer to `architecture/oidc-auth.md` in the repository.
+
+#### Logout
+
+To remove the stored OIDC tokens for the active gateway, run:
+
+```shell
+openshell gateway logout
+```
+
+This deletes `oidc_token.json` but keeps the gateway registration. The next `openshell` command prompts for re-authentication.
+
 ## File Layout
 
 All gateway credentials and metadata are stored under `~/.config/openshell/`:
@@ -95,5 +169,6 @@ openshell/
         tls.crt                     # Client certificate
         tls.key                     # Client private key
       edge_token                    # Edge auth JWT (cloud gateways)
+      oidc_token.json               # OIDC access and refresh tokens (oidc gateways)
       last_sandbox                  # Last-used sandbox for this gateway
 ```
@@ -31,6 +31,16 @@ OpenShell publishes standalone `openshell-gateway` release assets for manual dow
 
 These artifacts are attached to GitHub releases. `openshell gateway start` continues to use the published cluster and gateway container images.
 
+## Debian Packages
+
+OpenShell publishes Debian packages for Linux amd64 and arm64. Tagged releases attach `openshell_*.deb` artifacts to the GitHub release alongside the standalone binaries. The `dev` rolling tag carries the latest development build, which you can install with the `install-dev.sh` helper:
+
+```shell
+curl -fLsS https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install-dev.sh | sh
+```
+
+The package installs the CLI, gateway binary, and a `systemd` unit that runs the gateway as a service. Debian packaging is currently limited to Linux amd64 and arm64.
+
 ## Software Prerequisites
 
 The following software must be installed on the host before using the OpenShell CLI:

@@ -163,8 +163,17 @@ openshell gateway info --name my-remote-cluster
 | `--gpu` | Enable NVIDIA GPU passthrough. Requires NVIDIA drivers and the Container Toolkit on the host. OpenShell auto-selects CDI when enabled on the daemon and falls back to Docker's NVIDIA GPU request path (`--gpus all`) otherwise. |
 | `--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. |
+| `--drivers` | Compute driver to use for sandboxes. Accepts `kubernetes`, `podman`, `docker`, or `vm`. When unset, the gateway auto-detects in priority order: Kubernetes (when `KUBERNETES_SERVICE_HOST` is set), Podman, then Docker. The VM driver is never auto-detected and must be selected explicitly. |
 | `--registry-username` | Username for registry authentication. Defaults to `__token__` when `--registry-token` is set. Only needed for private registries. Also configurable with `OPENSHELL_REGISTRY_USERNAME`. |
 | `--registry-token` | Authentication token for pulling container images. For GHCR, a GitHub PAT with `read:packages` scope. Only needed for private registries. Also configurable with `OPENSHELL_REGISTRY_TOKEN`. |
+| `--oidc-issuer` | OIDC issuer URL. Setting this enables JWT validation on the gateway. |
+| `--oidc-audience` | Expected `aud` claim in validated JWTs. Defaults to `openshell-cli`. |
+| `--oidc-roles-claim` | Dot-separated JWT claim path that holds the user's roles. Defaults to `realm_access.roles`. |
+| `--oidc-admin-role` | Role required for admin operations such as provider mutation and global policy updates. Defaults to `openshell-admin`. |
+| `--oidc-user-role` | Role required for sandbox and read operations. Defaults to `openshell-user`. |
+| `--oidc-scopes-claim` | JWT claim path for scopes. Setting this layers fine-grained scope enforcement on top of roles. |
+
+For the full OIDC configuration reference and provider-specific examples, refer to [Gateway Authentication](/reference/gateway-auth#oidc).
 
 ## Stop and Destroy