---
title: OPENSHELL-GATEWAY
section: 8
header: OpenShell Manual
footer: openshell-gateway
date: 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**.

**--db-max-connections** *N*
:   Connection ceiling for the database pool, shared by every
    database-backed request. Must be at least 1, and at least 2 with
    Postgres, because the SSH identity lock keeps one connection while it
    queries the pool. When unset, the gateway uses the backend default:
    **10** for Postgres, **5** for on-disk SQLite. An in-memory SQLite
    database is always one connection.
    TOML key: `database_max_connections`.
    Environment: **OPENSHELL_DB_MAX_CONNECTIONS**.

**--db-lock-max-connections** *N*
:   Connection ceiling for the Postgres mutation lock pool, which each
    replica opens on top of its database pool. Each mutation guard holds
    one lock connection. Must be at least 1. When unset, the gateway uses
    **4**. SQLite has no lock pool and ignores it.
    TOML key: `database_lock_max_connections`.
    Environment: **OPENSHELL_DB_LOCK_MAX_CONNECTIONS**.

**--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/*