OpenShell/deploy/man/openshell-gateway.8.md

title, section, header, footer, date

title	section	header	footer	date
OPENSHELL-GATEWAY	8	OpenShell Manual	openshell-gateway	2025

NAME

openshell-gateway - OpenShell gateway server daemon

SYNOPSIS

openshell-gateway [OPTIONS]

openshell-gateway config preflight [--path PATH | -- GATEWAY_ARGS...]

DESCRIPTION

openshell-gateway is the control-plane server for OpenShell. It manages sandbox lifecycle, stores provider credentials, delivers network and filesystem policies to sandboxes, manages provider access requests, and provides the SSH tunnel endpoint for CLI-to-sandbox connections.

When installed via a Linux package, the gateway runs as a systemd user service. The packaged service starts from built-in defaults and reads the default gateway TOML path only when that file exists.

The gateway exposes a single port with multiplexed gRPC and HTTP, secured by mutual TLS (mTLS) by default unless the TOML config disables TLS.

OPTIONS

--bind-address IP

IP address to bind all listeners to. Default: 127.0.0.1. Environment: OPENSHELL_BIND_ADDRESS.

--port PORT

Port for the gRPC/HTTP API. Default: 17670. Environment: OPENSHELL_SERVER_PORT.

--health-port PORT

Port for unauthenticated health endpoints (/healthz, /readyz). Set to 0 to disable. Default: 0. Environment: OPENSHELL_HEALTH_PORT.

--metrics-port PORT

Port for Prometheus metrics (/metrics). Set to 0 to disable. Default: 0. Environment: OPENSHELL_METRICS_PORT.

--log-level LEVEL

Log level: trace, debug, info, warn, error. Default: info. Environment: OPENSHELL_LOG_LEVEL.

--db-url URL

SQLite database URL for state persistence. When unset, the gateway stores SQLite state under ~/.local/state/openshell/gateway/. Environment: OPENSHELL_DB_URL.

--compute-driver DRIVER

Compute driver. Selects exactly one driver. Options: podman, docker, kubernetes, vm. When unset, the gateway auto-detects Kubernetes, then Podman, then Docker. VM is opt-in. Environment: OPENSHELL_COMPUTE_DRIVER.

--tls-cert PATH

Path to server TLS certificate file. Defaults to the local generated TLS bundle when present. Required unless --disable-tls is set. Environment: OPENSHELL_TLS_CERT.

--tls-key PATH

Path to server TLS private key file. Defaults to the local generated TLS bundle when present. Required unless --disable-tls is set. Environment: OPENSHELL_TLS_KEY.

--tls-client-ca PATH

Path to CA certificate for client certificate verification (mTLS). When set without --oidc-issuer, client certificates are required and the TLS handshake rejects unauthenticated connections. When set together with --oidc-issuer, client certificates are accepted but not required. Client certificates can authenticate local single-user CLI callers when mTLS auth is enabled; sandbox supervisors still authenticate with gateway-minted bearer tokens. Environment: OPENSHELL_TLS_CLIENT_CA.

--enable-mtls-auth BOOL

Enable mTLS client certificate authentication for local single-user Docker, Podman, and VM gateways. Defaults on for local gateways with client certificate verification and no OIDC issuer. Not supported with the Kubernetes compute driver. Environment: OPENSHELL_ENABLE_MTLS_AUTH.

--disable-tls

Disable TLS entirely and listen on plaintext HTTP. When the bind address is 0.0.0.0 (the RPM default), disabling TLS exposes the API to the entire network without authentication. Only use when the gateway sits behind a TLS-terminating reverse proxy, or restrict --bind-address to 127.0.0.1. Environment: OPENSHELL_DISABLE_TLS.

--server-san SAN

Subject Alternative Name configured on the gateway server certificate. Repeat or pass a comma-separated value through OPENSHELL_SERVER_SAN. Wildcard DNS SANs also enable sandbox service URLs under that domain. Environment: OPENSHELL_SERVER_SAN.

Compute driver settings such as sandbox image, callback endpoint, image pull policy, network name, VM state directory, and guest TLS material are configured in the TOML file passed with --config.

CONFIGURATION PREFLIGHT

Validate a gateway configuration before starting the daemon:

openshell-gateway config preflight [--path PATH | -- GATEWAY_ARGS...]

With no path, preflight validates a nonempty OPENSHELL_GATEWAY_CONFIG. If that variable is unset, it optionally validates an auto-discovered XDG config. The absence of either config succeeds. An explicit missing path, legacy schema-v1 file, invalid TOML, symlink, or nonregular file fails with a nonzero status. Preflight merges file and environment values and applies read-only startup checks for selector and socket normalization, registered compute-driver configuration, rate limits, TLS and mTLS, interceptors, and middleware. When a selected file omits the selector, it validates configured tables for auto-detectable drivers without running socket or process-based detection probes. It does not construct a compute driver or connect to a transport. Preflight never changes the file and reports that failed input was preserved.

Arguments after -- replace --path mode and are parsed as the exact gateway daemon invocation. Package wrappers use this form so command-line overrides are validated before the same arguments reach startup.

The Debian and Ubuntu systemd user unit runs preflight before certificate generation, while retaining its EnvironmentFile and bare ExecStart behavior. The Snap wrapper replays its effective daemon arguments through preflight. It first uses a nonempty OPENSHELL_GATEWAY_CONFIG. Otherwise it passes the canonical SNAP_COMMON/gateway.toml path whenever it exists or is a symlink. A broken symlink fails preflight before the gateway is started. Correct or manually migrate an operator-owned v1 file, then run preflight again before restarting the service.

SYSTEMD INTEGRATION

The package installs a systemd user unit at /usr/lib/systemd/user/openshell-gateway.service. Manage the gateway with standard systemd commands:

systemctl --user enable --now openshell-gateway
systemctl --user status openshell-gateway
systemctl --user restart openshell-gateway
systemctl --user stop openshell-gateway

View logs:

journalctl --user -u openshell-gateway
journalctl --user -u openshell-gateway -f

The unit runs openshell-gateway config preflight and then openshell-gateway generate-certs as ExecStartPre steps. Certificate generation creates a self-signed PKI bundle for mTLS and sandbox JWT signing material, adding missing JWT files to older TLS-only installs when needed. The packaged unit sets OPENSHELL_LOCAL_TLS_DIR to ~/.local/state/openshell/tls and uses that same value for certificate generation and gateway startup. Override OPENSHELL_LOCAL_TLS_DIR in ~/.config/openshell/gateway.env only if you need a custom bundle location.

The gateway then starts from built-in defaults and reads ~/.config/openshell/gateway.toml when that file exists.

To persist the service across logouts:

sudo loginctl enable-linger $USER

CONFIGURATION

The systemd user unit launches the gateway with:

openshell-gateway

Gateway listener, TLS, database, and compute driver settings have local defaults. Create ~/.config/openshell/gateway.toml when you need to override them. The gateway rejects database_url in TOML; set OPENSHELL_DB_URL when you need a different database.

To override individual settings without creating TOML:

systemctl --user edit openshell-gateway

This creates a drop-in override that persists across package upgrades.

FILES

/usr/bin/openshell-gateway

Gateway binary.

/usr/lib/systemd/user/openshell-gateway.service

Systemd user unit file.

~/.config/openshell/gateway.toml

Optional gateway TOML configuration.

~/.local/state/openshell/tls/

Auto-generated TLS certificates and sandbox JWT signing keys.

~/.local/state/openshell/gateway/openshell.db

SQLite database for gateway state.

~/.config/openshell/gateways/openshell/mtls/

Client mTLS certificates for CLI auto-discovery.

EXAMPLES

Start the gateway as a systemd user service:

systemctl --user enable --now openshell-gateway

Check gateway health from the CLI:

openshell gateway add --local https://127.0.0.1:17670
openshell status

Override the API port in TOML:

$EDITOR ~/.config/openshell/gateway.toml
systemctl --user restart openshell-gateway

SEE ALSO

openshell(1), systemctl(1), journalctl(1), loginctl(1), podman(1)

Full documentation: https://docs.nvidia.com/openshell/