Gateway Configuration File

The OpenShell gateway reads its configuration from a TOML file when --config or OPENSHELL_GATEWAY_CONFIG is set. When neither is set, the gateway reads $XDG_CONFIG_HOME/openshell/gateway.toml if that file exists. If no config file exists, the gateway starts from built-in defaults. Gateway process flags and gateway OPENSHELL_* environment variables override the file. Compute driver settings live in the driver TOML tables. See RFC 0003 for the full schema.

Source Precedence

Gateway CLI flag  >  gateway OPENSHELL_* env var  >  TOML file  >  built-in default

database_url is env-only. The loader rejects it when it appears in the file. When OPENSHELL_DB_URL is unset, the gateway stores its SQLite database under $XDG_STATE_HOME/openshell/gateway/openshell.db.

Package-Managed Locations

Package-managed gateways do not require a TOML file. Create one at the package’s optional config location when you need to override built-in defaults. Set OPENSHELL_GATEWAY_CONFIG in the launch environment to use a different file.

Package	Optional Gateway TOML location
Homebrew	`$XDG_CONFIG_HOME/openshell/gateway.toml` when it exists, otherwise an existing Homebrew prefix config such as `/opt/homebrew/var/openshell/gateway.toml`.
Debian/Ubuntu	`$XDG_CONFIG_HOME/openshell/gateway.toml`, usually `~/.config/openshell/gateway.toml` for the systemd user service.
Fedora/RHEL RPM	`$XDG_CONFIG_HOME/openshell/gateway.toml`, usually `~/.config/openshell/gateway.toml` for the systemd user service.
Snap	`$SNAP_COMMON/gateway.toml`, usually `/var/snap/openshell/common/gateway.toml`.

Layout

The file is rooted at [openshell]. Gateway-wide settings live under [openshell.gateway]. Each compute driver owns its own [openshell.drivers.<name>] table. Shared keys set at gateway scope are inherited into driver tables when not overridden.

1 [openshell]
2 version = 1
3 
4 [openshell.gateway]
5 # ... gateway-wide settings ...
6 
7 [openshell.gateway.tls]
8 # ... gateway listener TLS ...
9 
10 [openshell.gateway.oidc]
11 # ... JWT bearer auth ...
12 
13 [openshell.drivers.kubernetes]
14 # ... driver-specific settings ...

Full Example

A complete gateway configuration covering every section. Trim to the fields you need.

1 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2 # SPDX-License-Identifier: Apache-2.0
3 
4 [openshell]
5 version = 1
6 
7 [openshell.gateway]
8 bind_address          = "0.0.0.0:8080"
9 health_bind_address   = "0.0.0.0:8081"
10 metrics_bind_address  = "0.0.0.0:9090"
11 
12 log_level             = "info"
13 
14 # When empty the gateway auto-detects (Kubernetes -> Podman -> Docker). VM is
15 # never auto-detected and requires an explicit entry here.
16 compute_drivers       = ["kubernetes"]
17 
18 sandbox_namespace     = "openshell"
19 
20 # Subject Alternative Names baked into the gateway server certificate.
21 # Wildcard DNS SANs (e.g. "*.dev.openshell.localhost") also enable sandbox
22 # service URLs under that domain.
23 server_sans                  = ["openshell", "*.dev.openshell.localhost"]
24 # Allow plaintext HTTP routing for loopback sandbox service URLs.
25 enable_loopback_service_http = true
26 
27 # Shared driver defaults — inherited into [openshell.drivers.<name>] tables
28 # when the driver-specific table does not override them.
29 default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
30 supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
31 client_tls_secret_name = "openshell-client-tls"
32 
33 # Gateway listener TLS (distinct from the per-driver guest_tls_*).
34 [openshell.gateway.tls]
35 cert_path             = "/etc/openshell/certs/gateway.pem"
36 key_path              = "/etc/openshell/certs/gateway-key.pem"
37 client_ca_path        = "/etc/openshell/certs/client-ca.pem"
38 
39 [openshell.gateway.gateway_jwt]
40 signing_key_path = "/etc/openshell/jwt/signing.pem"
41 public_key_path  = "/etc/openshell/jwt/public.pem"
42 kid_path         = "/etc/openshell/jwt/kid"
43 gateway_id       = "openshell"
44 ttl_secs         = 3600
45 
46 [openshell.gateway.auth]
47 allow_unauthenticated_users = false
48 
49 [openshell.gateway.oidc]
50 issuer        = "https://idp.example.com/realms/openshell"
51 audience      = "openshell-cli"
52 jwks_ttl_secs = 3600
53 roles_claim   = "realm_access.roles"
54 admin_role    = "openshell-admin"
55 user_role     = "openshell-user"

Local Docker, Podman, and VM gateways can also set [openshell.gateway.mtls_auth] enabled = true to authenticate CLI callers from verified client certificates. Kubernetes deployments must leave this unset and use OIDC or a trusted access proxy; the Helm chart does not render this table.

[openshell.gateway.auth] allow_unauthenticated_users = true is an unsafe local-development and trusted-proxy escape hatch. It accepts user-facing CLI/API calls without OIDC or mTLS credentials while sandbox supervisors still authenticate with gateway-minted sandbox JWTs. Leave it false for shared and production gateways.

Per-Driver Examples

Kubernetes

The gateway runs as a Pod and creates sandbox Pods in another namespace. mTLS material for sandboxes is delivered via a Kubernetes Secret rather than host-side file paths.

1 [openshell]
2 version = 1
3 
4 [openshell.gateway]
5 bind_address          = "0.0.0.0:8080"
6 health_bind_address   = "0.0.0.0:8081"
7 metrics_bind_address  = "0.0.0.0:9090"
8 log_level             = "info"
9 compute_drivers       = ["kubernetes"]
10 
11 default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
12 supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
13 client_tls_secret_name = "openshell-client-tls"
14 
15 [openshell.gateway.tls]
16 cert_path      = "/etc/openshell-tls/server/tls.crt"
17 key_path       = "/etc/openshell-tls/server/tls.key"
18 client_ca_path = "/etc/openshell-tls/client-ca/ca.crt"
19 
20 [openshell.drivers.kubernetes]
21 namespace                  = "agents"
22 grpc_endpoint              = "https://openshell-gateway.agents.svc:8080"
23 service_account_name       = "openshell-sandbox"
24 image_pull_policy          = "IfNotPresent"
25 # Use the image volume on K8s >= 1.35 (GA in 1.36); switch to "init-container"
26 # on older clusters or where the ImageVolume feature gate is off.
27 supervisor_sideload_method = "image-volume"

Docker

Sandboxes run as containers on a local bridge network. The supervisor binary is bind-mounted from the host (no in-cluster image pull required); guest mTLS material is supplied as host paths.

1 [openshell]
2 version = 1
3 
4 [openshell.gateway]
5 bind_address    = "127.0.0.1:17670"
6 log_level       = "info"
7 compute_drivers = ["docker"]
8 
9 supervisor_image = "ghcr.io/nvidia/openshell/supervisor:latest"
10 guest_tls_ca     = "/etc/openshell/certs/ca.pem"
11 guest_tls_cert   = "/etc/openshell/certs/client.pem"
12 guest_tls_key    = "/etc/openshell/certs/client-key.pem"
13 
14 [openshell.drivers.docker]
15 default_image    = "ghcr.io/nvidia/openshell/sandbox:latest"
16 image_pull_policy = "IfNotPresent"
17 sandbox_namespace = "docker-dev"
18 grpc_endpoint    = "https://host.openshell.internal:17670"
19 network_name     = "openshell-docker"
20 # Skip the image-pull-and-extract step by pointing at a locally built binary.
21 supervisor_bin   = "/usr/local/libexec/openshell/openshell-sandbox"

Podman

Sandboxes run as Podman containers on a user-mode bridge network. The supervisor image is mounted read-only via Podman’s type=image mount; guest mTLS material is supplied as host paths.

1 [openshell]
2 version = 1
3 
4 [openshell.gateway]
5 bind_address    = "127.0.0.1:17670"
6 log_level       = "info"
7 compute_drivers = ["podman"]
8 
9 default_image     = "ghcr.io/nvidia/openshell/sandbox:latest"
10 supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
11 guest_tls_ca      = "/etc/openshell/certs/ca.pem"
12 guest_tls_cert    = "/etc/openshell/certs/client.pem"
13 guest_tls_key     = "/etc/openshell/certs/client-key.pem"
14 
15 [openshell.drivers.podman]
16 # Rootless socket path. For root Podman use /run/podman/podman.sock.
17 socket_path       = "/run/user/1000/podman/podman.sock"
18 network_name      = "openshell"
19 stop_timeout_secs = 10
20 image_pull_policy = "missing"   # Podman vocabulary: always | missing | never | newer

MicroVM

Each sandbox runs inside its own libkrun microVM managed by the standalone openshell-driver-vm subprocess. Use this driver when you want stronger isolation than container namespaces alone.

1 [openshell]
2 version = 1
3 
4 [openshell.gateway]
5 bind_address    = "127.0.0.1:17670"
6 log_level       = "info"
7 # VM is never auto-detected; an explicit entry here is required.
8 compute_drivers = ["vm"]
9 
10 default_image  = "ghcr.io/nvidia/openshell/sandbox:latest"
11 guest_tls_ca   = "/var/lib/openshell/guest-tls/ca.pem"
12 guest_tls_cert = "/var/lib/openshell/guest-tls/client.pem"
13 guest_tls_key  = "/var/lib/openshell/guest-tls/client-key.pem"
14 
15 [openshell.drivers.vm]
16 grpc_endpoint = "https://host.containers.internal:17670"
17 state_dir      = "/var/lib/openshell/vm"
18 # Where the gateway looks for the openshell-driver-vm subprocess binary.
19 driver_dir     = "/usr/local/libexec/openshell"
20 vcpus          = 2
21 mem_mib        = 2048
22 krun_log_level = 1