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.

--enable-operator-auth BOOL

Enable direct mTLS operators with a trusted client certificate containing OU=operator. Grants user/platform-admin capabilities across all workspaces and access to runtime credential retrieval. Defaults off. Requires TLS and a client CA, independently of ordinary mTLS user auth and OIDC. Do not combine an operator certificate with bearer headers. Environment: OPENSHELL_ENABLE_OPERATOR_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 still validates the effective daemon arguments. 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.

An explicitly selected local vm driver also checks mke2fs or mkfs.ext4, debugfs, and e2fsck. Install e2fsprogs 1.43 or newer with the operating system's package manager, then run preflight with the gateway service's account, working directory, configuration, and environment. The command reports selected executable paths and versions. A restricted service PATH can select different tools from an interactive shell; include the installation's bin and sbin directories in that service's environment.

Each executable receives only -V, with a five-second deadline and an 8 KiB output limit per stream. Missing, non-executable, unsupported, or failing tools return nonzero status with installation or repair guidance. Preflight creates no images or runtime state and does not start the VM driver. Other drivers do not require these tools. A remote driver endpoint reports that host tool checks were not performed; check a local VM configuration on that host in the driver service's environment.

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 service-specific gateway.toml path whenever it exists or is a symlink. The legacy system service uses SNAP_COMMON/gateway.toml; the user service uses SNAP_USER_COMMON/.config/openshell/gateway.toml. 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.

The user service also reads ~/.config/openshell/gateway.env for both config preflight and startup. OPENSHELL_SANDBOX_RUNTIME_IMAGE and OPENSHELL_SUPERVISOR_IMAGE accept complete tagged or digest-pinned OCI references for the built-in Docker, Podman, and Kubernetes drivers. These variables take precedence over explicit image fields in the selected driver's TOML table, which take precedence over compiled release defaults. These are trusted gateway inputs and cannot be supplied by sandbox requests. Do not embed registry credentials in image references.

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/