fix(packaging): use gateway TOML config in packages

Author: drew

deploy/deb/init-gateway-config.sh

@@ -15,11 +15,29 @@ fi
 
 mkdir -p "$(dirname "$CONFIG_FILE")" "$VM_STATE_DIR"
 
+toml_string() {
+    printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+bind_address="${OPENSHELL_BIND_ADDRESS:-127.0.0.1}"
 port="${OPENSHELL_SERVER_PORT:-17670}"
+case "$bind_address" in
+    *:*) listen_address="[${bind_address}]:${port}" ;;
+    *) listen_address="${bind_address}:${port}" ;;
+esac
+
 scheme="https"
-if [ "${OPENSHELL_DISABLE_TLS:-false}" = "true" ]; then
-    scheme="http"
-fi
+disable_tls="false"
+case "${OPENSHELL_DISABLE_TLS:-false}" in
+    1 | true | TRUE | yes | YES | on | ON)
+        disable_tls="true"
+        scheme="http"
+        ;;
+esac
+
+tls_cert="${OPENSHELL_TLS_CERT:-${PKI_DIR}/server/tls.crt}"
+tls_key="${OPENSHELL_TLS_KEY:-${PKI_DIR}/server/tls.key}"
+tls_client_ca="${OPENSHELL_TLS_CLIENT_CA:-${PKI_DIR}/ca.crt}"
 
 tmp="${CONFIG_FILE}.tmp"
 {
@@ -28,23 +46,30 @@ tmp="${CONFIG_FILE}.tmp"
 version = 1
 
 [openshell.gateway]
+bind_address = "$(toml_string "$listen_address")"
+disable_tls = ${disable_tls}
 default_image = "ghcr.io/nvidia/openshell-community/sandboxes/base:latest"
 supervisor_image = "ghcr.io/nvidia/openshell/supervisor:latest"
 EOF
 
     if [ "$scheme" = "https" ]; then
         cat <<EOF
-guest_tls_ca = "${PKI_DIR}/ca.crt"
-guest_tls_cert = "${PKI_DIR}/client/tls.crt"
-guest_tls_key = "${PKI_DIR}/client/tls.key"
+guest_tls_ca = "$(toml_string "${PKI_DIR}/ca.crt")"
+guest_tls_cert = "$(toml_string "${PKI_DIR}/client/tls.crt")"
+guest_tls_key = "$(toml_string "${PKI_DIR}/client/tls.key")"
 EOF
     fi
 
     cat <<EOF
 
+[openshell.gateway.tls]
+cert_path = "$(toml_string "$tls_cert")"
+key_path = "$(toml_string "$tls_key")"
+client_ca_path = "$(toml_string "$tls_client_ca")"
+
 [openshell.drivers.vm]
-state_dir = "${VM_STATE_DIR}"
-driver_dir = "${DRIVER_DIR}"
+state_dir = "$(toml_string "$VM_STATE_DIR")"
+driver_dir = "$(toml_string "$DRIVER_DIR")"
 grpc_endpoint = "${scheme}://127.0.0.1:${port}"
 
 [openshell.drivers.docker]

deploy/deb/openshell-gateway.service

@@ -6,18 +6,13 @@ After=default.target
 [Service]
 Type=simple
 StateDirectory=openshell/gateway
-# %S resolves to $XDG_STATE_HOME for user services.
-Environment=OPENSHELL_BIND_ADDRESS=127.0.0.1
-Environment=OPENSHELL_SERVER_PORT=17670
-Environment=OPENSHELL_TLS_CERT=%S/openshell/tls/server/tls.crt
-Environment=OPENSHELL_TLS_KEY=%S/openshell/tls/server/tls.key
-Environment=OPENSHELL_TLS_CLIENT_CA=%S/openshell/tls/ca.crt
-Environment=OPENSHELL_DB_URL=sqlite:%S/openshell/gateway/openshell.db
-Environment=OPENSHELL_GATEWAY_CONFIG=%S/openshell/gateway/config.toml
+# Legacy OPENSHELL_* overrides are still honored, but packaged defaults live
+# in %S/openshell/gateway/config.toml. %S resolves to $XDG_STATE_HOME for user
+# services.
 EnvironmentFile=-%h/.config/openshell/gateway.env
 ExecStartPre=/usr/bin/openshell-gateway generate-certs --output-dir %S/openshell/tls --server-san host.openshell.internal
-ExecStartPre=/usr/libexec/openshell/init-gateway-config.sh %S/openshell/gateway/config.toml %S/openshell/tls /usr/libexec/openshell %S/openshell/vm-driver
-ExecStart=/usr/bin/openshell-gateway
+ExecStartPre=/bin/sh -c 'exec /usr/libexec/openshell/init-gateway-config.sh "$${OPENSHELL_GATEWAY_CONFIG:-%S/openshell/gateway/config.toml}" %S/openshell/tls /usr/libexec/openshell %S/openshell/vm-driver'
+ExecStart=/bin/sh -c 'exec /usr/bin/openshell-gateway --config "$${OPENSHELL_GATEWAY_CONFIG:-%S/openshell/gateway/config.toml}" --db-url "$${OPENSHELL_DB_URL:-sqlite:%S/openshell/gateway/openshell.db}"'
 Restart=on-failure
 RestartSec=5s
 PrivateTmp=true

deploy/man/openshell-gateway.8.md

@@ -22,12 +22,13 @@ network and filesystem policies to sandboxes, routes inference
 requests, and provides the SSH tunnel endpoint for CLI-to-sandbox
 connections.
 
-When installed via RPM, the gateway runs as a systemd user service
-with the Podman compute driver. Sandboxes are rootless Podman
-containers on the host.
+When installed via a Linux package, the gateway runs as a systemd user
+service. The packaged service creates a gateway TOML file on first
+start and launches the gateway with **--config**.
 
-The gateway exposes a single port (default 8080) with multiplexed
-gRPC and HTTP, secured by mutual TLS (mTLS) by default.
+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
 
@@ -100,7 +101,7 @@ configured in the TOML file passed with **--config**.
 
 # SYSTEMD INTEGRATION
 
-The RPM installs a systemd user unit at
+The package installs a systemd user unit at
 */usr/lib/systemd/user/openshell-gateway.service*. Manage the gateway
 with standard systemd commands:
 
@@ -114,13 +115,13 @@ View logs:
     journalctl --user -u openshell-gateway
     journalctl --user -u openshell-gateway -f
 
-The unit runs two **ExecStartPre** scripts on first start:
+The unit runs two **ExecStartPre** steps on first start:
 
-1. **init-pki.sh** generates a self-signed PKI bundle for mTLS.
-2. **init-gateway-env.sh** generates the environment configuration
-   file.
+1. **openshell-gateway generate-certs** generates a self-signed PKI
+   bundle for mTLS.
+2. **init-gateway-config.sh** generates the gateway TOML file.
 
-Both scripts are idempotent and skip generation if their output files
+Both steps are idempotent and skip generation if their output files
 already exist.
 
 To persist the service across logouts:
@@ -129,11 +130,20 @@ To persist the service across logouts:
 
 # CONFIGURATION
 
-The systemd user unit reads configuration from
-*~/.config/openshell/gateway.env*. See **openshell-gateway.env**(5)
-for the full variable reference.
+The systemd user unit launches the gateway with:
 
-To override individual settings without modifying gateway.env:
+    openshell-gateway --config ~/.local/state/openshell/gateway/config.toml \
+      --db-url sqlite:~/.local/state/openshell/gateway/openshell.db
+
+Gateway listener, TLS, and compute driver settings live in
+*~/.local/state/openshell/gateway/config.toml*. The database URL stays
+on **--db-url** because the gateway rejects `database_url` in TOML.
+
+For compatibility, the unit also reads optional environment overrides
+from *~/.config/openshell/gateway.env*. Gateway environment variables
+in that file continue to override TOML values.
+
+To override individual settings without modifying the generated TOML:
 
     systemctl --user edit openshell-gateway
 
@@ -147,19 +157,19 @@ This creates a drop-in override that persists across package upgrades.
 */usr/lib/systemd/user/openshell-gateway.service*
 :   Systemd user unit file.
 
-*/usr/libexec/openshell/init-pki.sh*
-:   PKI bootstrap script.
-
-*/usr/libexec/openshell/init-gateway-env.sh*
-:   Gateway environment file generator.
+*/usr/libexec/openshell/init-gateway-config.sh*
+:   Gateway TOML file generator.
 
 *~/.config/openshell/gateway.env*
-:   Gateway environment configuration (generated on first start).
+:   Optional legacy environment overrides.
+
+*~/.local/state/openshell/gateway/config.toml*
+:   Gateway TOML configuration (generated on first start).
 
 *~/.local/state/openshell/tls/*
 :   Auto-generated TLS certificates.
 
-*~/.local/state/openshell/gateway.db*
+*~/.local/state/openshell/gateway/openshell.db*
 :   SQLite database for gateway state.
 
 *~/.config/openshell/gateways/openshell/mtls/*
@@ -176,11 +186,10 @@ Check gateway health from the CLI:
     openshell gateway add --local https://127.0.0.1:8080
     openshell status
 
-Override the API port via a systemd drop-in:
+Override the API port in the generated TOML:
 
-    systemctl --user edit openshell-gateway
-    # Add: [Service]
-    # Add: Environment=OPENSHELL_SERVER_PORT=9090
+    $EDITOR ~/.local/state/openshell/gateway/config.toml
+    systemctl --user restart openshell-gateway
 
 # SEE ALSO
 

deploy/man/openshell-gateway.env.5.md

@@ -8,15 +8,15 @@ date: 2025
 
 # NAME
 
-openshell-gateway.env - OpenShell gateway environment configuration
+openshell-gateway.env - legacy OpenShell gateway environment overrides
 
 # DESCRIPTION
 
-The **openshell-gateway.env** file contains environment variables that
-configure the OpenShell gateway server when running as a systemd user
-service. It is generated automatically on first start by
-**init-gateway-env.sh** and is not overwritten on subsequent starts or
-package upgrades.
+The **openshell-gateway.env** file contains optional environment
+overrides for the OpenShell gateway server when running as a systemd
+user service. Packaged defaults live in the gateway TOML file; this
+environment file is kept for compatibility and for settings that must
+remain outside TOML, such as **OPENSHELL_DB_URL**.
 
 The file uses the standard systemd **EnvironmentFile** format: one
 **KEY=VALUE** pair per line. Lines beginning with **#** are comments.
@@ -33,62 +33,64 @@ The systemd user unit reads it via:
     EnvironmentFile=-~/.config/openshell/gateway.env
 
 The **-** prefix means the service starts normally if the file does not
-exist (the unit has built-in defaults for all required settings).
+exist.
 
 # VARIABLES
 
 ## Gateway
 
-**OPENSHELL_BIND_ADDRESS** (default: 0.0.0.0)
-:   IP address to bind all listeners to. The RPM default of **0.0.0.0**
-    exposes the gateway on all network interfaces; mTLS must remain
-    enabled to prevent unauthenticated access. Set to **127.0.0.1** for
-    local-only access.
+**OPENSHELL_BIND_ADDRESS**
+:   IP address to bind all listeners to. Overrides
+    `bind_address` in the TOML file.
 
-**OPENSHELL_SERVER_PORT** (default: 8080)
-:   Port for the multiplexed gRPC/HTTP API.
+**OPENSHELL_SERVER_PORT**
+:   Port for the multiplexed gRPC/HTTP API. Overrides the port in the
+    TOML `bind_address`.
 
-**OPENSHELL_HEALTH_PORT** (default: 0)
+**OPENSHELL_HEALTH_PORT**
 :   Port for unauthenticated health endpoints (/healthz, /readyz).
     Set to a non-zero value to enable a dedicated health listener.
 
-**OPENSHELL_METRICS_PORT** (default: 0)
+**OPENSHELL_METRICS_PORT**
 :   Port for Prometheus metrics endpoint (/metrics). Set to a
     non-zero value to enable a dedicated metrics listener.
 
-**OPENSHELL_LOG_LEVEL** (default: info)
+**OPENSHELL_LOG_LEVEL**
 :   Log verbosity: **trace**, **debug**, **info**, **warn**, **error**.
 
-**OPENSHELL_DRIVERS** (default: podman)
+**OPENSHELL_DRIVERS**
 :   Compute driver for sandbox management. Options: **podman**,
-    **docker**, **kubernetes**. The RPM unit defaults to **podman**.
+    **docker**, **kubernetes**, **vm**. Overrides `compute_drivers` in
+    the TOML file.
 
-**OPENSHELL_DB_URL** (default: sqlite://$XDG_STATE_HOME/openshell/gateway.db)
-:   SQLite database URL for gateway state persistence.
+**OPENSHELL_DB_URL**
+:   SQLite database URL for gateway state persistence. The gateway
+    rejects `database_url` in TOML, so packages pass this value through
+    **--db-url** when it is set.
 
 ## TLS
 
-**OPENSHELL_TLS_CERT** (default: auto-generated path)
+**OPENSHELL_TLS_CERT**
 :   Path to server TLS certificate.
 
-**OPENSHELL_TLS_KEY** (default: auto-generated path)
+**OPENSHELL_TLS_KEY**
 :   Path to server TLS private key.
 
-**OPENSHELL_TLS_CLIENT_CA** (default: auto-generated path)
+**OPENSHELL_TLS_CLIENT_CA**
 :   Path to CA certificate for client certificate verification. When
     set without **OPENSHELL_OIDC_ISSUER**, mTLS is required. When both
     are set, callers may authenticate via Bearer token or client
     certificate.
 
-**OPENSHELL_DISABLE_TLS** (default: unset)
+**OPENSHELL_DISABLE_TLS**
 :   Set to **true** to disable TLS entirely and listen on plaintext
-    HTTP. Not recommended for production. When the bind address is
-    **0.0.0.0** (the RPM default), disabling TLS exposes the API to the
-    entire network without authentication. Restrict
+    HTTP. Not recommended for production. When the bind address is a
+    public interface, disabling TLS exposes the API to the network
+    without authentication. Restrict
     **OPENSHELL_BIND_ADDRESS** to **127.0.0.1** or place the gateway
     behind a TLS-terminating reverse proxy.
 
-**OPENSHELL_SERVER_SAN** (default: unset)
+**OPENSHELL_SERVER_SAN**
 :   Comma-separated SANs configured on the gateway server certificate.
     Wildcard DNS SANs also enable sandbox service URLs under that
     domain.

deploy/snap/README.md

@@ -140,21 +140,20 @@ override is required. The OpenShell snap still requires the Docker snap because
 it relies on the `docker:docker-daemon` slot; it does not work with Docker
 installed from a Debian package or Docker's upstream packages.
 
-The service runs the gateway with the Docker driver enabled:
+The service runs the gateway with an explicit config file and database URL:
 
 ```shell
 openshell.gateway \
-  --drivers docker \
-  --disable-tls \
-  --port 17670 \
-  --db-url "sqlite:$SNAP_COMMON/gateway.db?mode=rwc" \
-  --config "$SNAP_COMMON/gateway.toml"
+  --config "$SNAP_COMMON/gateway.toml" \
+  --db-url "sqlite:$SNAP_COMMON/gateway.db?mode=rwc"
 ```
 
 This stores the gateway SQLite database at
 `/var/snap/openshell/common/gateway.db`. The generated TOML stores Docker
-driver settings such as the supervisor binary path, network name, sandbox
-namespace, sandbox image, pull policy, and callback endpoint.
+gateway settings such as the bind address, plaintext TLS mode, and selected
+compute driver, plus Docker driver settings such as the supervisor binary path,
+network name, sandbox namespace, sandbox image, pull policy, and callback
+endpoint.
 
 ## Connect with the OpenShell CLI
 

deploy/snap/bin/openshell-gateway-wrapper

@@ -5,15 +5,21 @@
 set -eu
 
 CONFIG_FILE="${OPENSHELL_GATEWAY_CONFIG:-${SNAP_COMMON}/gateway.toml}"
+DB_URL="${OPENSHELL_DB_URL:-sqlite:${SNAP_COMMON}/gateway.db?mode=rwc}"
 
 if [ ! -f "$CONFIG_FILE" ]; then
     mkdir -p "$(dirname "$CONFIG_FILE")"
     cat > "$CONFIG_FILE" << EOF
 [openshell]
 version = 1
 
-[openshell.drivers.docker]
+[openshell.gateway]
+bind_address = "127.0.0.1:17670"
+disable_tls = true
+compute_drivers = ["docker"]
 default_image = "ghcr.io/nvidia/openshell-community/sandboxes/base:latest"
+
+[openshell.drivers.docker]
 image_pull_policy = "IfNotPresent"
 sandbox_namespace = "docker-snap"
 grpc_endpoint = "http://host.openshell.internal:17670"
@@ -24,4 +30,4 @@ EOF
 fi
 
 export OPENSHELL_GATEWAY_CONFIG="$CONFIG_FILE"
-exec "${SNAP}/bin/openshell-gateway" "$@"
+exec "${SNAP}/bin/openshell-gateway" --config "$CONFIG_FILE" --db-url "$DB_URL" "$@"

deploy/snap/meta/snap.yaml.in

@@ -35,12 +35,6 @@ apps:
     daemon: simple
     refresh-mode: endure
     environment:
-      OPENSHELL_BIND_ADDRESS: 127.0.0.1
-      OPENSHELL_SERVER_PORT: 17670
-      OPENSHELL_DB_URL: "sqlite:$SNAP_COMMON/gateway.db?mode=rwc"
-      OPENSHELL_DISABLE_TLS: true
-      OPENSHELL_DRIVERS: docker
-      OPENSHELL_GATEWAY_CONFIG: "$SNAP_COMMON/gateway.toml"
       XDG_DATA_HOME: "$SNAP_COMMON"
       # Used for creating and locating certain sockets.
       XDG_RUNTIME_DIR: "$SNAP_COMMON"