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
For Helm deployments, see Configure Chart Values
for setting gatewayConfig and chart-owned Kubernetes resources.
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.
On-disk SQLite databases run in WAL mode with synchronous=FULL: the gateway keeps openshell.db-wal and openshell.db-shm next to the database file, the file must live on a local filesystem, and a backup must use sqlite3 openshell.db ".backup <copy>" rather than copying openshell.db on its own. Every acknowledged write, including SSH session revocations, survives a power loss. The one exception is SSH session issuance, which skips the per-commit sync; a power loss can drop a just-issued session token, and the client must request a new one.
Trusted runtime image overrides
Docker, Podman, and Kubernetes consume two gateway-owned trusted runtime images. Set complete tagged or digest-pinned OCI references for the gateway process when you need to qualify exact artifacts or use a registry mirror:
These settings follow the gateway’s normal environment-over-file precedence:
openshell-gateway config preflight and gateway startup use the same effective
references. Environment values are handled exactly like the corresponding TOML
fields and passed to the selected container runtime; this feature does not add
separate OCI-reference validation. Configure registry credentials in Docker,
Podman, or Kubernetes image-pull secrets instead of embedding them in a
reference.
The variables affect only the built-in Docker, Podman, and Kubernetes drivers.
They do not affect VM, MXC, or extension drivers. They are trusted gateway
operator inputs and are never accepted from sandbox create requests. For
Debian and RPM user services, place them in
~/.config/openshell/gateway.env; the service supplies that file to both
preflight and gateway startup.
name assigns an operator-facing identity to the gateway installation. Set it with [openshell.gateway].name, --name, or OPENSHELL_GATEWAY_NAME. It defaults to openshell; the Helm chart defaults it to the chart fullname so all replicas in one installation share a name. Chart fullnames are only unique within their Kubernetes namespace, so set server.name explicitly when one collector receives telemetry from multiple namespaces or clusters. This identity is independent of client-side gateway aliases, TLS names, and gateway_jwt.gateway_id.
Package-Managed Locations
Package-managed gateways use either built-in defaults or a package-seeded TOML file. Set OPENSHELL_GATEWAY_CONFIG in the launch environment to use a different file.
The Fedora/RHEL RPM template leaves [openshell.gateway].bind_address unset. The gateway therefore uses its built-in 127.0.0.1:17670 primary listener. Host-networked Podman supervisors use that same loopback endpoint, so the primary listener does not need a wildcard address. Set bind_address explicitly only when clients must reach the primary multiplexed API through another interface.
The Homebrew formula creates its prefix config without setting bind_address, so the gateway uses its built-in 127.0.0.1:17670 primary listener. Host-networked Docker and Podman supervisors reuse that listener when the desktop runtime exposes host loopback. A user config takes precedence.
Homebrew and RPM upgrades migrate only exact package-generated schema-v1 defaults. Homebrew recognizes both its empty v1 prefix config and the affected IPv6-loopback variant. RPM recognizes the v1 file seeded by its systemd user service. Package upgrades never rewrite an edited file; migrate an edited v1 file manually with the steps below.
Layout
The file is rooted at [openshell]. Gateway-wide settings live under [openshell.gateway]. Each compute driver owns its own [openshell.drivers.<name>] table. Credential drivers own [openshell.credential_drivers.<name>] tables. Driver-specific values are never inherited from gateway scope.
The gateway selector is compute_driver = "<driver>". It accepts one scalar driver name. Omit it to retain auto-detection.
Migrate to schema version 2
Schema version 2 is an intentional breaking cutover. The gateway rejects files
that omit [openshell] version, declare version 1, or declare an unsupported
future version. To migrate an existing file:
- Set
[openshell] version = 2. - Replace
compute_drivers = ["<name>"]with the scalarcompute_driver = "<name>". Replace--driversandOPENSHELL_DRIVERSwith--compute-driverandOPENSHELL_COMPUTE_DRIVER. Package upgrades temporarily accept one non-emptyOPENSHELL_DRIVERSvalue as a deprecated environment-only alias when it agrees with any canonical selection. Comma-delimited, invalid, or conflicting legacy values fail startup. The removed--driverand--driversflags remain unsupported. - Move every compute-driver option into
[openshell.drivers.<name>]. Schema version 2 does not inherit driver defaults from[openshell.gateway]. Keepguest_tls_caat gateway scope and removeguest_tls_certandguest_tls_key. A TLS-enabled Docker, Podman, or VM gateway requires the gateway CA unless package-managed local TLS supplies it. When TLS is disabled, omit it. Kubernetes projects the gateway CA into supervisor Pods throughclient_tls_secret_nameinstead. - Rename Docker
sandbox_namespacetosandbox_label, Podmansandbox_ssh_socket_pathtossh_socket_path, and VMopenshell_endpointtogrpc_endpoint. - Use canonical image pull policies:
always,if_not_present,never, or Podman-onlynewer. Kubernetes-style capitalization and Podman’smissingspelling are rejected. - Remove zero sentinels. Omit
gateway_jwt.ttl_secsto use non-expiring local sandbox session credentials and the 900-second typed extension-token default, omit Docker or Podmansandbox_pids_limitto use OpenShell’s default limit of 2048, and omit Podmanhealth_check_interval_secsto disable health checks. Explicit zero values are invalid. - Remove local Docker, Podman, or VM
grpc_endpointwhen the driver-derived callback is correct, or retain it as an explicit override. Kubernetes raw TOML requires an explicit endpoint; Helm derives one from the release’s gateway Service. New VM root filesystems use an image-providedsandboxaccount when present and otherwise use UID/GID 1000. Existing persisted VM state retains its recorded or recoverable identity, including legacy 10001; the driver does not assign 10001 to an overlay without supporting state.
Every [openshell.drivers.<name>] entry must be a TOML table. The gateway
validates driver-specific fields when it selects and constructs that driver;
it does not deserialize unselected driver tables. Unknown or misplaced fields
in the selected table fail startup instead of being silently ignored.
Full Example
A complete gateway configuration covering every section. Trim to the fields you need.
Set [openshell.gateway.mtls_auth] enabled = true to map a verified client certificate to a CLI user identity. This gateway policy is independent of the compute driver and defaults on when a client CA is configured without OIDC. The listener allows bearer-only clients and validates any client certificate presented against the configured CA. Supervisors use guest_tls_ca to authenticate the gateway and sandbox bearer tokens to authenticate their RPCs.
Set [openshell.gateway.mtls_auth] operator_enabled = true,
--enable-operator-auth true, or OPENSHELL_ENABLE_OPERATOR_AUTH=true to enable
direct mTLS operators. The default is false. TLS and a client CA are required.
This setting is independent of enabled and OIDC. A verified certificate with
the exact OU=operator grants user/platform-admin capabilities across all
workspaces and access to GetProviderCredentials. Do not combine an operator
certificate with an Authorization header. See
Authentication for the
certificate trust boundary.
The client-certificate handshake policy has no require_client_auth TOML field. Client certificates are optional at the transport layer; gateway RPC authorization enforces the configured user or sandbox identity.
[openshell.gateway.tls] supports optional SNI-based dual-certificate mode for deployments that need separate internal and external server certificates. Set external_cert_path and external_key_path to point at the external (e.g. ACME/publicly-trusted) certificate and key. List the hostnames that should be served with the external certificate in external_server_names. Connections whose TLS SNI hostname matches one of those names receive the external certificate; all other connections (including those with no SNI) receive the primary internal certificate from cert_path/key_path. Both fields must be set together — providing only one is a configuration error. On Kubernetes with the Helm chart, the external certificate is managed automatically when certManager.serverIssuerRef.name is set; the chart populates these fields from the cert-manager-issued external server certificate.
[openshell.gateway] policy_validation_failure_mode controls what sandbox supervisors do when a complete candidate policy fails runtime validation. The default, fail_closed, deactivates the previous network policy, closes relays pinned to it, and denies new egress until a valid generation loads. retain_last_valid leaves the previous valid generation active. Both modes reject the candidate atomically; startup keeps the workload unstarted until the effective policy and matching provider configuration pass admission. A rejected startup exposes ConfigurationInvalid and remains available for policy/provider repair in either mode. Gateway mutation paths that can preflight a known effective scope reject invalid candidates before persistence and leave the active policy unchanged regardless of this setting. Changing the value requires restarting the gateway so it can reload gateway.toml and distribute the new posture to sandbox supervisors.
[openshell.gateway.gateway_jwt] ttl_secs controls generation-bound gateway-facing and Sandbox Protocol credentials minted for a sandbox session, plus typed extension JWTs. Omit it for non-expiring local sandbox session credentials: both session tokens carry exp = 0, supervisors skip periodic session-token renewal, and refresh responses omit their expiration timestamps. Typed extension JWTs retain a 900-second default when the field is omitted. Use omission only for local single-player Docker, Podman, or VM gateways. Explicit 0 is invalid. Kubernetes and other shared deployments should set a positive TTL; Helm renders 3600 seconds by default, and the gateway logs a warning when a Kubernetes gateway omits the field.
Listener TLS and sandbox launch signing use separate keys. A working HTTPS listener or mTLS client certificate does not supply the signing key needed to start a VM sandbox. Configure signing_key_path, public_key_path, kid_path, and gateway_id in [openshell.gateway.gateway_jwt], as shown above. For a local installation, openshell-gateway generate-certs --output-dir <tls-dir> writes a signing bundle alongside the TLS bundle. Without explicit gateway_jwt configuration, the gateway discovers jwt/signing.pem, jwt/public.pem, and jwt/kid under OPENSHELL_LOCAL_TLS_DIR, or under the OpenShell state directory’s tls/ directory when that variable is unset. Explicit signing configuration takes precedence over local discovery.
The gateway rejects partial or invalid signing bundles at startup, including private and public keys that do not match. When the selected driver requires launch signing and no bundle is configured, sandbox creation fails before the driver validates or prepares the sandbox. The error names the signing configuration and discovery location; it does not print keys or tokens. The VM driver also validates launch material before resolving images or creating sandbox state.
External compute drivers declare this requirement by adding openshell.compute.launch-authentication to their extension metadata’s required_capabilities. This requires a gateway that understands the launch-signing preflight and supplies SandboxLaunchAuthentication on creation. Drivers that use another launch mechanism can omit the requirement. The separate supports_sandbox_authentication capability describes the AuthenticateSandbox RPC and does not require launch signing.
[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.
Database Pool
[openshell.gateway] database_max_connections sets the connection ceiling for the gateway’s database pool. One pool is shared by every database-backed RPC, so this value is also the gateway’s ceiling on concurrent database work. When the pool is saturated, callers queue on connection acquisition and sqlx logs that the time to acquire a connection exceeded its slow threshold. The background readiness monitor draws from the same pool, so sustained saturation can push its database ping past the check timeout and flip /readyz to not-ready while the gateway is otherwise serving.
Omit the key to use the backend default, which is unchanged from earlier releases:
The equivalent flag and environment variable are --db-max-connections and OPENSHELL_DB_MAX_CONNECTIONS, and Helm deployments set the key under gatewayConfig.openshell.gateway. Values below 1 are rejected at startup: a zero-sized pool would block every acquisition rather than degrade. Postgres needs at least 2, because the SSH identity lock keeps one data connection while it queries the pool, so the gateway rejects 1 there too.
On Postgres, the gateway holds its mutation advisory locks on a separate lock pool, one connection per guarded mutation while it runs or waits. [openshell.gateway] database_lock_max_connections sets that pool’s ceiling, 4 by default, so it bounds how many guarded mutations a replica runs or waits on in Postgres at once. When every lock connection is in use, further guarded mutations queue for one, and fail with MUTATION_LOCK_TIMEOUT only if none frees up before their 10-second lock wait runs out. The equivalent flag and environment variable are --db-lock-max-connections and OPENSHELL_DB_LOCK_MAX_CONNECTIONS, and Helm deployments set the key under gatewayConfig.openshell.gateway. Values below 1 are rejected at startup. SQLite has no lock pool, so the gateway ignores the key there and logs that it did.
On Postgres, each replica opens both pools, so plan for (database_max_connections + database_lock_max_connections) × replicaCount connections, 14 per replica with the defaults, and keep that total below the server’s own max_connections (and below any connection-pooler limit in front of it). Rollouts run extra pods; refer to Size PostgreSQL Connections. Raising either ceiling past what the server admits moves the failure from a slow acquire to a refused connection.
On SQLite, writers are serialized regardless of pool size, so a larger ceiling buys read concurrency only. A gateway that needs more write throughput wants an external Postgres database (server.externalDbSecret), not a larger SQLite pool.
OCSF JSONL Output
[openshell.gateway.ocsf_log] enables a gateway-local file containing native OCSF events emitted by the gateway, including events without a sandbox association. Omit the table to disable it. Restart the gateway after changing this configuration.
Gateway records use [openshell.gateway] name as device.uid and device.name, shared across replicas; device.hostname identifies the replica. Assign a distinct name to each installation collected together. The default name does not guarantee uniqueness, and renaming an installation changes its audit identity.
Unknown fields are rejected. This is one file destination, not an exporter registry. To send the same events to a collector, use OCSF log export. The existing ocsf_json_enabled sandbox setting remains independent.
For Helm installations, set server.ocsfLog.enabled to render this table and optionally set server.ocsfLog.schemaVersion. The default server.ocsfLog.path, /tmp/gateway-ocsf.jsonl, is writable in the gateway container with either the StatefulSet or Deployment workload but does not persist across pod restarts. To keep records, mount a volume with server.extraVolumes and server.extraVolumeMounts and set the path on it. When replicas share a volume, add subPathExpr: $(OPENSHELL_POD_NAME) to the mount so each replica writes its own file.
Give each gateway replica its own writable file and an external shipper read access to the containing directory. New files use owner-only permissions on Unix; arrange shipper access deliberately. Rotation renames the active file to a date- and UUID-suffixed sibling. The shipper must follow rotated files and checkpoint its progress. Do not use multiple writers or external copy-truncate rotation on this path.
The gateway queues OCSF independently of RUST_LOG, excludes ordinary diagnostics, and preserves native event IDs. It writes up to 100 records per batch with a 500 ms batching interval. One additional bounded batch can be in flight. File errors do not stop sandbox execution: failed writes are not replayed, and subsequent records are discarded during reopen backoff. A restarted writer removes an incomplete trailing line before appending.
Metrics include openshell_ocsf_log_queued_total, openshell_ocsf_log_written_total, openshell_ocsf_log_queue_records, openshell_ocsf_log_queue_bytes, openshell_ocsf_log_dropped_total (with a bounded reason label), and openshell_ocsf_log_writer_errors_total. Recovery reports discarded bytes through openshell_ocsf_log_recovery_discarded_bytes_total, not an invented lost-record count. Warnings report writer failures independently of this file.
Allow enough retention and disk space for shipper outages. Graceful shutdown allows five seconds for draining; outstanding OS writes remain uncertain if they outlast that budget. Flush does not mean fsync. The file is a best-effort collection boundary, not durable acceptance, a replay protocol, or proof of a complete audit history. See OCSF JSON export for the separate sandbox-local output.
OTLP Export
[openshell.gateway.otlp] enables OpenTelemetry export over OTLP/gRPC. Omit the table to disable export. Its endpoint is the collector for every signal the gateway exports and, on its own, enables trace export. [openshell.gateway.otlp.traces] sends spans to a different collector. OCSF log export is off until [openshell.gateway.otlp.ocsf] sets enabled = true, and can use its own collector.
The gateway already uses the Rust tracing framework for structured logs sent to stdout and the sandbox log stream. Enabling this section adds an OpenTelemetry layer to the same tracing subscriber. It exports span trees to an OTLP collector without exporting, replacing, or redirecting the existing diagnostic log events.
Each enabled signal needs an endpoint, either in its own table or from endpoint. Endpoints must be valid URIs. If one is malformed, the gateway logs the configuration error and continues with all OTLP export disabled. It does not connect at startup: an unreachable collector produces export failures, never a failure to serve.
The transport is OTLP over gRPC only. HTTP/protobuf and HTTP/JSON are not supported, and OTEL_EXPORTER_OTLP_PROTOCOL has no effect. Point each endpoint at a collector’s gRPC receiver, conventionally port 4317, not the HTTP receiver on 4318. A URI alone cannot distinguish the two, so an HTTP endpoint is accepted at startup and then fails on export.
Use an https:// endpoint for TLS. The gateway verifies the collector certificate against the system trust roots.
The OpenTelemetry SDK logs export failures after startup. Spans in a failed batch are dropped rather than retried.
service_name sets the gateway’s service.name resource attribute and defaults to openshell-gateway.
The gateway passes the trace endpoint to compute drivers and sandbox supervisors, which export their own spans to it, so the trace collector must also be reachable from sandboxes. Spans for routine or high-volume operations use DEBUG level and are exported only when the gateway or sandbox log level is debug. For what is traced, span names, and resource attributes, refer to Traces.
For Helm deployments, set server.otlp.endpoint to render this table. The
optional server.otlp.serviceName value overrides the gateway service name;
driver service names remain fixed. Set the traces and ocsf tables through
gatewayConfig, which renders each key as a TOML table:
The local mise run helm:k3s:create workflow installs a trace collector and UI,
enables Agent Sandbox controller tracing on supported releases, and configures
both the controller and the existing Skaffold deployment to export traces to it
automatically.
The local gateway, gateway:docker, gateway:podman, and gateway:vm tasks
also set the gateway installation name in their generated configuration. Their
defaults are driver-specific (kubernetes-dev, docker-dev, podman-dev, and
vm-dev), and their documented OPENSHELL_*_GATEWAY_NAME overrides update both
CLI registration and exported telemetry identity.
Run mise run helm:k3s:forward to forward OTLP/gRPC to local port 4317 and
the trace UI to local port 18888. When Skaffold has deployed a Kubernetes
gateway, the task also forwards it to local port 8090; otherwise it continues
with the collector ports only. The Skaffold run task registers the forwarded
gateway under the worktree-specific k3d cluster name; select it with
openshell gateway select <name>. The local Podman, Docker, and VM gateway
tasks export spans and OCSF log records to the forwarded receiver
automatically.
In-process compute drivers read their backend-specific settings from [openshell.drivers.<name>]. An external driver’s gateway table supplies only its socket_path; configure the external driver process itself through that binary’s flags or environment variables. A driver that advertises supports_sandbox_authentication may authenticate an opaque bootstrap credential through the compute-driver protocol. It must return the same non-empty runtime identity from sandbox creation and credential authentication. Start requests include the previously recorded opaque identity so the driver can preserve the stable resource while rotating generation-specific compute. For IssueSandboxToken, the gateway verifies the sandbox exists and the driver/runtime identity matches the durable provisioning record before returning a generation-bound session JWT. The in-process Kubernetes driver reads service_account_name, workspace_mode, and namespace discovery from [openshell.drivers.kubernetes]; an external Kubernetes driver receives the equivalent values through its own CLI or environment contract.
OCSF Log Export
Set enabled = true in [openshell.gateway.otlp.ocsf] to export gateway OCSF events as OTLP log records. It defaults to false, so trace export alone never sends OCSF events. Records go to the table’s endpoint, or to [openshell.gateway.otlp] endpoint when it is omitted, with the same resource attributes as spans, under the openshell.ocsf instrumentation scope. Use a separate endpoint to send OCSF events to a collector that feeds a SIEM while spans go elsewhere. Sandbox supervisors receive the same endpoint and schema version and export their own OCSF events there directly, so the endpoint must also be reachable from sandboxes. Supervisor records carry the supervisor’s resource attributes, including openshell.sandbox.id and openshell.gateway.name. Supervisors also send the collector headers that the gateway uses for OCSF export, from OTEL_EXPORTER_OTLP_LOGS_HEADERS or else OTEL_EXPORTER_OTLP_HEADERS, so a collector that requires authentication accepts their records too. The gateway delivers the headers with each sandbox’s launch credentials, never through the sandbox environment. Other OTEL_* variables do not reach supervisors.
Each OCSF event becomes one log record:
Log export is independent of RUST_LOG and of [openshell.gateway.ocsf_log]; you can enable both. The gateway queues up to 10,000 records, and up to 16 MiB of records including the batch being exported, without blocking event producers. It exports a batch as soon as 100 records or 1 MiB are queued, or 500 ms after the first record of a batch arrives. A record larger than 1 MiB, such as an event for a request with a very long path, is dropped rather than exported.
A failed batch is retried with backoff for up to four attempts, so delivery is at least once. Deduplicate on ocsf.metadata.uid. Each attempt can take up to the exporter timeout, 10 seconds by default, so an unresponsive collector can hold a batch for about 40 seconds while new records fill the queue. Records in a batch that still fails, records rejected because the queue is full, and oversized records are dropped and counted. The next exported batch then includes a WARN record with event name openshell.ocsf.gap, the number of dropped records in openshell.ocsf.gap.dropped, and the time of the first loss in openshell.ocsf.gap.since_unix_ms. During shutdown, the gateway attempts each remaining batch once within a five-second budget, then abandons any export still in progress. Records lost during shutdown produce no gap record.
A collector can accept a batch while rejecting some of its records, an OTLP partial success. The gateway counts such a batch as exported, and the exporter logs the number of rejected records as a warning. Gap records and openshell_ocsf_otlp_dropped_total cover only records the gateway dropped, so check the collector’s own metrics for records it rejected.
Metrics include openshell_ocsf_otlp_queued_total, openshell_ocsf_otlp_exported_total, openshell_ocsf_otlp_dropped_total (with a reason label of queue_capacity, queue_bytes, oversized, export_failed, serialization, or closed), openshell_ocsf_otlp_export_errors_total, and openshell_ocsf_otlp_retries_total.
Tuning
[openshell.gateway.otlp] decides whether and where to export. How the SDK exports is controlled by the standard OpenTelemetry environment variables, which the gateway reads through the SDK rather than mirroring as TOML keys. They apply to the gateway and its in-process compute drivers. The gateway does not pass them to sandbox supervisors, which receive only the endpoints, the OCSF schema version, and the OCSF collector headers.
The gateway honors these variables:
These variables have no effect. Only [openshell.gateway.otlp] decides which signals are exported and where they go, for two reasons:
- OCSF events are security records, so where they go must be a deliberate choice. Platform tooling can add
OTEL_*variables to a process, as the OpenTelemetry Operator does for annotated pods on Kubernetes. Such a variable must not start sending security records to a collector, redirect them, or turn them off. - The gateway passes its export settings to compute drivers and sandbox supervisors. Supervisors run in each sandbox and do not inherit the gateway’s environment, so they could not follow a setting that exists only there.
To sample 10% of traces:
The gateway flushes buffered spans during shutdown, so spans from in-flight requests survive a SIGTERM.
Supervisor Middleware Services
Register operator-run supervisor middleware services with one or more [[openshell.supervisor.middleware]] entries. Registration is static and operator-owned; changing it requires restarting the gateway.
Each service implements the supervisor middleware gRPC contract and exposes bindings through Describe. Policies reference the operator-owned registration name, attaching the complete middleware and all of its bindings. Bindings are identified by operation and phase. A manifest may expose at most one binding for each operation and phase pair. V1 supports HttpRequest/pre_credentials, HttpResponse/pre_return, and WebSocketMessage/pre_credentials. Registration names must be unique, and operator-run registrations cannot claim the reserved openshell/ namespace. The service-reported manifest name is diagnostic metadata and does not need to match the registration name.
The gateway connects to every registered service and validates Describe before it starts. The service must therefore be running before the gateway. Policy creation and full policy updates call ValidateConfig; an unavailable service or invalid middleware configuration rejects the policy before persistence.
Startup also requires compatible extension protocol metadata. Upgrade legacy gateways and operator-run services together during a coordinated outage; neither mixed legacy/current pairing is supported. A service rejects a gateway that omits peer metadata, and a gateway rejects a service that omits metadata, uses another protocol major, or requires unsupported gateway capabilities. Protected GetGatewayInfo and openshell gateway info report the resulting non-secret snapshot.
max_payload_bytes is the shared operator limit for inspectable logical payloads across every binding exposed by the service. It caps HTTP request and response units, replacement bodies, and complete WebSocket text messages and replacements. Whole-response inspection uses it as the stage’s total body limit. Streaming response inspection applies it to each unit. The value must be greater than zero, no larger than each binding’s advertised max_payload_bytes capability, and no larger than the 4 MiB platform maximum. OpenShell rejects oversized values instead of silently clamping them. Binary WebSocket messages are not exposed to V1 middleware, so this field does not limit binary pass-through. Middleware gRPC servers should allow messages of at least 4 MiB plus 293 KiB so a maximum-size payload and its protobuf envelope fit on the transport.
timeout is the operator-configured service-wide RPC timeout. It accepts the same compact duration syntax as gateway interceptors: an integer followed by ms or s, such as 500ms or 2s. Values must be between 10ms and 30s, inclusive. Omit the field to use the 500 ms platform default. A binding may advertise a shorter timeout in the Describe manifest, but it cannot extend the operator-configured deadline; OpenShell uses the smaller value. OpenShell validates both levels before accepting the service. The operator-configured service timeout applies to Describe and ValidateConfig. The effective binding timeout applies to HTTP request evaluation, HTTP response preflight and unit exchanges, WebSocket preflight, and each WebSocket message. Accepted streaming protocols have no connection-wide RPC deadline.
The service grpc_endpoint supports plaintext http:// and TLS https://. HTTPS uses the platform trust store unless tls_ca_cert_path names a certificate-only PEM bundle. OpenShell rejects bundles containing private keys, loads the certificates at gateway startup, and distributes only public certificates to sandbox supervisors; normal TLS hostname verification still applies. audience sets the exact audience for gateway-minted service tokens and defaults to urn:openshell:extension:middleware:<name>. After authenticated Describe succeeds, OpenShell treats a non-empty manifest expected_audience as a consistency assertion and refuses to start when it differs from the configured audience. A strict verifier may reject an incorrect audience before returning the manifest.
When gateway_jwt is configured, OpenShell attaches short-lived bearer credentials to gateway and supervisor calls and requires https://. A middleware endpoint must be reachable from sandbox supervisors, so Unix sockets are not an option here. Set allow_insecure_transport = true on a registration to keep a plaintext http:// endpoint: OpenShell then attaches no credential, supervisors do not request one, and the gateway logs a warning naming the registration at every startup. mTLS client authentication, health checks, and runtime registration are not currently supported. The endpoint must be reachable from both the gateway and sandbox supervisors; use host.openshell.internal or another shared address that can be resolved in both places.
See Supervisor Middleware Configuration for attachment, failure, and operational guidance.
Gateway Interceptors
[[openshell.gateway.interceptors]] configures gateway-side interceptor services. The gateway calls each service’s Describe RPC at startup, validates its declared OpenShell RPC bindings against the compiled service descriptor, and applies matching phases from a central gRPC middleware path. Interceptors can target only methods in the gateway’s built-in allowlist of unary mutation RPCs. New RPCs are non-interceptable until they are deliberately added to that allowlist; adding one does not require handler-specific interceptor code. Request bodies are exposed as protobuf JSON objects. Fields marked secret in the protobuf schema are recursively omitted from requests and post-commit responses. Interceptors cannot patch an omitted field or a containing object.
Each interceptor must also complete extension protocol negotiation during Describe. Upgrade legacy gateways and interceptors together during a coordinated outage; neither mixed legacy/current pairing is supported. The interceptor rejects missing or incompatible gateway metadata, and the gateway rejects missing metadata, incompatible protocol majors, and unmet requirements before serving requests.
HTTPS interceptor endpoints use the platform trust store by default. Set tls_ca_cert_path to a PEM certificate bundle for a private CA; normal TLS hostname verification still applies. audience sets the exact audience for gateway-minted service tokens and defaults to urn:openshell:extension:interceptor:<name>. After authenticated Describe succeeds, the gateway treats a non-empty manifest expected_audience as a consistency assertion and refuses to start when it differs from the configured audience. A strict verifier may reject an incorrect audience before returning the manifest. When gateway_jwt is configured, network interceptors must use HTTPS and receive short-lived gateway-caller bearer credentials; local Unix sockets are also supported. Set allow_insecure_transport = true to keep a plaintext http:// interceptor endpoint with no credential attached and a startup warning.
Extension Token Verification Endpoints
When gateway_jwt is configured the gateway publishes two unauthenticated documents that extension services use to verify OpenShell callers:
The discovery document is OIDC-shaped rather than OIDC-compliant: issuer is the gateway identity (openshell-gateway:<gateway_id>), not the URL the document is served from. Verifiers compare iss against that value and must not infer trust from the document’s location; the serving TLS connection is what authenticates the gateway. Both endpoints return 404 when gateway_jwt is not configured.
binding_policy controls how the manifest and operator binding configuration combine:
dynamicenables valid manifest bindings and treats configured entries as optional narrowing overrides. This is the compatibility default. The gateway logs a startup warning because the interceptor controls its non-secret RPC authority.allowlistenables only configured RPC selectors and phases. The gateway ignores and logs extra manifest declarations, but fails startup when the manifest omits a configured RPC or phase.exactrequires the configured and manifest RPC selectors and phases to match exactly.
Bindings under allowlist and exact require rpc or service plus method, and a nonempty phases list. They match by RPC rather than manifest binding ID. Duplicate selectors, id, and disabled are invalid in these modes; omit a binding to disable it. Binding failure policy comes from the binding, then the configured service, then defaults to fail_closed. Manifest failure policies do not override strict-mode operator configuration.
Bindings that include post_commit must resolve to failure_policy = "fail_open"; the gateway rejects fail-closed post-commit configuration at startup. Post-commit evaluation is observational. If response observation or interceptor evaluation fails after a handler succeeds, the gateway logs and counts the failure but returns the committed response unchanged.
provider_profile_sources selects the exact ordered provider-profile source set. Omit it to use imported profiles only. Use { type = "user" } and { type = "interceptor", name = "<configured-interceptor-name>" } entries to compose a catalog. An interceptor entry must reference a configured service whose manifest advertises provider_profiles = true. Selecting only an interceptor makes that catalog authoritative; include { type = "user" } explicitly to compose imported profiles with it. Empty or duplicate source lists, unknown interceptor names, and duplicate normalized profile IDs fail closed. Source order controls collection and diagnostics, not override precedence.
OpenShell ships no profiles inside the gateway binary. A gateway with nothing imported reaches ready and serves an empty catalog; import the profiles it needs with openshell provider profile import. The builtin source type was removed and a configuration that still names it is rejected at startup.
For an authoritative interceptor catalog, select only that interceptor:
The gateway validates snapshot structure and provider-profile semantics. It treats a configured interceptor as the source trust boundary and does not verify signature, hash, or key annotations in profile payloads.
failure_policy accepts fail_closed or fail_open. timeout accepts ms and s suffixes. In dynamic mode, binding overrides may select a manifest binding by id, rpc, or service plus method; they can disable a binding, narrow its phases, or override its failure policy.
image_pull_policy is a shared driver setting with the canonical values always, if_not_present, never, and newer. Set it inside the relevant driver table. Drivers translate these values to their runtime APIs; newer is supported only by Podman and is rejected at Docker and Kubernetes startup.
Credential Drivers
Set credential_drivers only when the gateway should store provider secrets in an external credential backend. Provider secrets include injectable credentials and gateway-only refresh material such as OAuth refresh tokens, client secrets, and service-account private keys. OpenShell supports at most one enabled credential driver at a time. When credential_drivers is omitted, the gateway uses its default encrypted database credential storage. credential_drivers = [] is invalid in the TOML file; omit the field for the default encrypted store, or select a backend such as kubernetes-secrets or vault.
Credential driver tables are backend-owned and live under [openshell.credential_drivers.<name>]. Built-in drivers default to in-tree transport, so they do not need a transport field. Use transport = "uds" with an absolute socket_path only for a remote gRPC driver over a Unix domain socket.
For Kubernetes Secrets:
For Vault instead:
For the default encrypted database store, OpenShell stores provider credentials as JSON envelopes encrypted with AES-256-GCM in the gateway database. Each credential gets a random data-encryption key; the gateway wraps that key with a local key-encryption key. By default, the key-encryption key is created at $XDG_STATE_HOME/openshell/gateway/credentials/key-encryption-key.bin with owner-only permissions. Use [openshell.gateway.credential_storage] key_encryption_key_env instead of key_encryption_key_path to load a base64-encoded 32-byte key-encryption key from an environment variable. Back up the database and key-encryption key together; losing either makes stored credentials unrecoverable. In Kubernetes, the Helm chart creates a retained Secret containing the shared key-encryption key, injects it as OPENSHELL_GATEWAY_CREDENTIAL_KEY_ENCRYPTION_KEY, and renders key_encryption_key_env for the gateway when no external credential driver is enabled. Multi-replica deployments need every replica to use the same database and key-encryption key; the chart default handles the key-encryption key side.
For GitOps and helm template workflows where lookup returns empty, the chart-generated KEK Secret gets a random value on every render, making credentials unrecoverable. Set server.credentialStorage.existingSecret to the name of a pre-provisioned Secret containing the key-encryption key under the key-encryption-key data key. When set, the chart skips KEK Secret generation and references the provided Secret directly.
For kubernetes-secrets, namespace sets where OpenShell-managed provider Secret objects are stored in every workspace mode. When omitted, the driver uses the in-cluster ServiceAccount namespace when available, otherwise default. The driver rejects credential handles that reference any other namespace. The Helm chart creates a Role granting the gateway access to all Secrets in the credential namespace because OpenShell-managed Secret names are dynamic SHA-256 hashes that cannot be restricted with resourceNames; the gateway ClusterRole grants no credential Secret permissions. Deploy credential Secrets in a dedicated namespace (server.credentialDrivers.kubernetesSecrets.namespace) to limit the RBAC blast radius. When the credential namespace is the release namespace, the Role also covers the gateway’s own TLS and database Secrets. Set server.credentialDrivers.kubernetesSecrets.createNamespace=true to have the chart create the dedicated namespace. The chart retains it on uninstall so stored credentials survive, and leaves an existing namespace it does not own untouched.
For vault, address points at the Vault service. Non-loopback endpoints must use HTTPS; plaintext HTTP is accepted only for localhost or an IP loopback address during local development. Vault requests do not follow redirects, preventing credentials from being replayed to a downgraded or substituted endpoint. HTTPS uses platform trust roots by default. Set ca_bundle to a certificate-only PEM bundle for a private Vault CA; the bundle augments platform roots and normal hostname verification remains enabled. mount and kv_version describe the KV engine where OpenShell-managed provider secrets are stored, and auth_method = "kubernetes" logs in with the gateway Pod’s ServiceAccount token. For local or development validation, use auth_method = "token_file" with token_path = "/path/to/token". Do not put literal Vault tokens in TOML.
For Helm deployments, set credentialDrivers.vault.caConfigMapName to a ConfigMap containing the private CA bundle under the ca.crt key. The chart mounts that key and derives ca_bundle automatically.
Provider records that already contain inline database credentials remain readable for upgrade compatibility. New provider create/update requests still submit credential values through the normal API, but the gateway stores those values through the active credential storage path and persists only handles. Before OpenShell 0.1.0, OpenShell does not automatically migrate inline refresh material or credential handles between drivers. Reconfigure refresh grants after an upgrade. Before changing credential drivers, remove affected credentials while the original driver is still available, then select the new driver and create them again. Do not run mixed gateway versions against the same refresh records.
For remote credential drivers, set transport = "uds" with socket_path. Omit command, args, and startup_timeout_secs when another service manager prestarts the driver socket. Keep backend tokens out of TOML; point the driver at mounted token files or native identity mechanisms instead.
The built-in kubernetes-secrets and vault drivers can also run out of
process over UDS. Set command to the standalone driver binary and pass
driver-specific settings through args; the gateway appends --bind-socket <socket_path> when it launches the process.
Gateway Peer Routing
Multi-replica gateways relay session-bound traffic to the replica that owns a sandbox supervisor. The Helm chart sets these variables; set them manually only outside the chart.
The gateway refuses to start when a peer endpoint is configured on a multi-replica backend and peer authentication is unavailable, because the replica could not serve relays from its peers. That happens when the pod identity variables are missing, when the in-cluster Kubernetes client cannot be built, or when the gateway is not running in a cluster. A plaintext http:// peer endpoint is also rejected when the gateway serves TLS; use it only when the gateway itself serves plaintext.
Driver References
External Resource Admission
Every compute driver disables caller-supplied template.driver_config by
default. An operator can enable it without disabling resource approval:
Use the same fields under the selected Docker, Podman, VM, MXC, or external
driver table. Omitted admission settings use the labels above. A supplied map
replaces the defaults, and every entry must match. An explicitly empty map is
invalid while enforcement is enabled. ${workspace} is the entire label value
and resolves to the authorized OpenShell workspace name, not a Kubernetes
namespace or caller label. Other substitutions and expressions are unsupported.
At least one fixed label is required so intentionally shared resources still
need explicit operator approval.
The following label keys are reserved for driver-owned metadata and cannot be
used in required_labels: openshell.ai/managed-by, openshell.ai/gateway-id,
and openshell.ai/sandbox-workspace. The default admission key
openshell.ai/sandbox-attachable-workspace is distinct from the reserved
sandbox metadata key.
The operator must label the referenced resource before use. Labels on a sandbox
do not approve its attachments. For example, a PVC used by workspace team-a
needs this metadata:
Kubernetes checks caller-selected PVCs, RuntimeClasses, and PriorityClasses through the OpenShell-owned Pod template. Docker and Podman check engine volume labels. Read-only mounts still require approval. Namespaces do not grant approval. Newly provisioned private storage and bootstrap material use driver ownership checks instead.
Kubernetes PVC mount destinations must not overlap the driver-managed
/.openshell tree or /run, including mounts using sub_path. Approval labels
do not override these restrictions. Mount application data at paths such as
/data or a directory below /sandbox.
RuntimeClasses and PriorityClasses are shared operator infrastructure. They must
match every fixed required label, but ${workspace} entries do not apply to
them. Kubernetes API-server and admission-webhook mutations of the live Pod are
trusted cluster-operator behavior and are not used as Workspace User
authorization inputs.
Image-pull Secrets are selected by gateway configuration, not by sandbox callers, and do not participate in resource admission. In managed mode OpenShell creates an immutable copy of each configured Secret for every sandbox runtime generation and deletes it with that generation. Sandbox creation fails if a Secret with the generation name already exists. In shared and operator modes, the configured Secret must already exist in the sandbox namespace. The typed Kubernetes driver config does not support caller-selected Secret or ConfigMap volumes or environment references. Automatic service-account tokens and projected token volumes are prohibited.
GPU device attachments are temporarily exempt from label admission. Existing
GPU validation still applies. Explicit GPU device settings inside driver JSON
still require allow_driver_config = true; public GPU-count requests do not.
The exception does not approve unrelated host mounts or non-GPU devices.
Raw host bind mounts and supplemental image mounts have no trusted label resolver and are rejected while admission is enabled. Publisher image labels cannot grant operator approval. Docker’s existing unsupported image-mount restriction remains. MXC host filesystem grants likewise require disabling admission until a resolver exists. MXC’s command config and VM upload workflows encoded in driver JSON require explicit driver-config opt-in.
allow_driver_config applies to nonempty caller config, including saved
templates and non-storage overrides. An absent config or {} does not require
opt-in. Drivers recheck admitted OpenShell input attachments before launch and
on restart; running Docker, Podman, and Kubernetes workloads are periodically
revalidated.
Confirmed revocation stops or suspends the workload. Metadata lookup outages
block new launches but do not alone stop existing workloads. Revalidation uses
the Docker observation loop (normally two seconds) or a 30-second Podman /
Kubernetes interval, plus lookup and retry time. These are not instantaneous
revocation guarantees.
To explicitly opt out of label authorization:
This does not enable driver JSON or bypass existing path, ownership, namespace, or isolation validation. It relinquishes external-resource label protection for that driver. Restart the gateway and driver after policy changes. Only trusted operators should control approval labels, runtime APIs, and resource replacement; application admission is not atomic mount authorization.
Before upgrading, inventory and approve legitimate external resources. Legacy sandbox state without verifiable admission provenance requires recreation; OpenShell does not automatically approve old attachments. Remove stale labels before reusing a deleted workspace name. A custom approval-only map permits cross-workspace sharing and should be an intentional operator decision.
Standalone Kubernetes, Podman, and VM drivers accept the common policy as
--admission-config-json or OPENSHELL_DRIVER_ADMISSION_CONFIG_JSON; {} uses
secure defaults. Docker also accepts the fields in its driver TOML file. The
gateway-managed VM process receives the selected gateway policy automatically.
Operator-managed external processes must be configured separately. Their
versioned GetCapabilities.resource_admission_policy acknowledgement must
match the gateway policy; legacy drivers require an explicit admission opt-out.
A changed acknowledgement blocks subsequent remote validation/create/start
calls until gateway and driver configuration agree again.
Helm exposes server.drivers.kubernetes.allowDriverConfig,
resourceAdmission.enabled, and resourceAdmission.requiredLabels. The label
map defaults to null, which uses code defaults without merging those keys
into a custom map. The Helm chart grants PVC metadata reads only when
allowDriverConfig is enabled. Split workspace releases must set the matching
gateway.allowDriverConfig=true workspace-chart value. Never mark gateway
database storage as attachable.
Each example is a complete TOML file for one compute driver. The examples repeat [openshell] and [openshell.gateway] so they stay copyable, and the driver tables list the accepted driver-specific keys. Drivers receive only their own tables, and the gateway rejects unknown gateway and driver fields.
Kubernetes configurations set namespace, service_account_name, and enable_user_namespaces in [openshell.drivers.kubernetes]. Docker configurations use sandbox_label; the legacy sandbox_namespace key is rejected.
Kubernetes
The gateway runs as a Pod and creates paired workload and supervisor Pods in another namespace. The gateway CA is projected from a Kubernetes Secret into supervisor Pods; user client certificate and key entries in that Secret are not exposed to either Pod.
The Kubernetes driver always creates the workload NetworkPolicy before
releasing a sandbox Pod. Your cluster CNI must enforce ingress and egress
NetworkPolicy in every sandbox namespace; the Kubernetes API does not verify
enforcement.
In managed workspace mode, the Kubernetes driver copies each explicitly named
image_pull_secrets Secret from namespace into the managed workspace
namespace on sandbox creation. Shared and operator modes require the Secret to
already exist in the sandbox namespace.
For token-exchange provider profiles, the gateway also needs access to its own
SPIFFE Workload API socket. In Helm deployments, set
server.providerTokenGrants.spiffe.enabled=true; the chart mounts the socket
into the gateway pod and sets OPENSHELL_GATEWAY_SPIFFE_WORKLOAD_API_SOCKET.
The gateway verifies supervisor JWT-SVIDs with JWT bundles fetched from the
SPIFFE Workload API, so this validation path does not require gateway access to
the SPIRE OIDC discovery endpoint or its TLS CA.
MXC
The MXC driver runs Windows workloads through wxc-exec. Enable ETW auditing to
map Windows Sandboxing provider events into the gateway’s OCSF stream.
etw_audit defaults to false. When enabled, the gateway account must be an
administrator or belong to the Windows Performance Log Users group. Workload
commands and working directories remain sandbox-scoped and must be supplied in
the mxc driver configuration when creating a sandbox.
OPENSHELL_OCSF_JSON=1 enables the gateway’s JSONL audit
sink independently of the selected compute driver. Set OPENSHELL_OCSF_LOG_DIR
to override the default %PROGRAMDATA%\OpenShell\logs directory on Windows
or $XDG_STATE_HOME/openshell/logs on Unix. Prefer the gateway’s configured
ocsf_log output for retention controls and loss metrics.
The driver records executable identity in process audit events and omits raw command arguments because they can contain credentials or personal data. See OCSF JSON Export for durable Windows audit output.
Docker
Each Docker sandbox uses a workload container with networking disabled and a host-networked supervisor container. Configure the supervisor gateway CA once under [openshell.gateway]; the gateway validates and injects it into the selected local driver. The supervisor authenticates RPCs with a sandbox bearer token.
Use sandbox_label for Docker configurations.
supervisor_network_mode accepts host (the default), bridge, or auto.
auto also selects host; the driver does not infer a mode from the workload runtime.
The workload always uses network=none.
Omit grpc_endpoint for automatic selection: host mode uses loopback; bridge
uses host.docker.internal on Desktop or with a wildcard listener, otherwise
the Linux listener’s non-loopback address.
Docker’s host address is discovered automatically for bridge mode and gateway
endpoints using host.docker.internal. Set host_gateway_ip only to override it.
In bridge mode, host services and the configured OTLP collector endpoint must
be reachable from containers; native Linux loopback-only listeners are unreachable.
Host mode on Docker Desktop requires host networking enabled.
Docker accepts http:// and https:// proxy URLs in explicit
scheme://host:port form. no_proxy bypasses only the corporate proxy;
OpenShell policy still applies. Proxy URLs cannot embed credentials. Supply a
user:pass file with proxy_auth_file, and set
proxy_auth_allow_insecure = true only to acknowledge that Basic credentials
travel in cleartext to an http:// proxy.
proxy_ca_bundle requires https_proxy, but the configured proxy URL may use
either scheme because a plain HTTP proxy can still intercept destination TLS.
The file must be a readable, bounded PEM bundle containing a usable certificate
authority. Docker validates it at gateway startup and again before each
supervisor launch. Missing, unreadable, empty, oversized, malformed, and
certificate-free bundles fail closed rather than falling back to default trust
or direct egress.
The gateway-host path is operator-owned and cannot be selected through sandbox
environment, image contents, or template.driver_config.docker. The driver
copies the validated contents into its supervisor-only named volume and passes
the fixed path /.openshell/supervisor/upstream-proxy-ca-bundle.pem to the
companion supervisor. The bundle extends trust for the TLS connection to an
https:// proxy, supervisor connections to re-signed upstream certificates,
and the combined trust bundle exposed to workload processes. The gateway-host
path is never mounted into or exposed to the workload container.
Podman
Each Podman sandbox uses two containers. The workload container runs openshell-sandbox with network=none; the supervisor container runs on the host network and initiates policy-approved upstream connections. A private volume carries their authenticated Unix-domain socket. Configure the supervisor gateway CA once under [openshell.gateway]; the gateway validates and injects it into the selected local driver. The supervisor authenticates RPCs with a sandbox bearer token.
Caller cdi_devices entries must be valid CDI qualified names
(<vendor>/<class>=<name>). Host-device paths are rejected. See
GPU selection.
Use ssh_socket_path for Podman configurations. The legacy
sandbox_ssh_socket_path key is rejected. When app_armor_profile is omitted,
OpenShell sends no override and Podman applies its runtime-selected profile.
The setting applies to the workload container; the supervisor retains Podman’s
runtime-selected profile.
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.
The example uses explicit launch-signing paths. Point them at an existing signing bundle, or omit the gateway_jwt table to use local discovery. Listener and guest TLS certificates do not supply these signing credentials.
To generate a local bundle for discovery, run these commands in fish and retain the same environment when starting the gateway:
The command also installs local CLI mTLS credentials. For explicit signing configuration, set the example’s signing paths to jwt/signing.pem, jwt/public.pem, and jwt/kid under that directory. The gateway loads those paths in preference to local discovery.
Rootfs tar staging requires the gateway and the VM driver to share a filesystem
and run as the same user. That holds for the managed VM driver, which the
gateway starts as a subprocess. If you point compute_driver_endpoints at an
externally managed vm socket owned by another user, the driver cannot read the
gateway’s staging directory and rootfs tar sources fail with a
FAILED_PRECONDITION error; use a registry image reference instead.
Extension Driver
Extension drivers run outside the gateway and expose the
compute_driver.proto gRPC service on a Unix socket. Use a non-reserved driver
name; built-in names such as vm, docker, podman, and kubernetes cannot
be selected through unmanaged socket endpoints. The selected driver name is the
key used for driver-owned sandbox config such as template.driver_config.<name>.
Preflight package configuration {#gateway-config-preflight}
Before starting a package-managed gateway, validate the selected file without changing it:
Without --path, the command validates a nonempty OPENSHELL_GATEWAY_CONFIG. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight merges the selected file with the current OPENSHELL_* environment and applies the daemon’s read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits compute_driver, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration.
Config preflight validates configuration without loading launch-signing keys, so a successful result does not confirm that the key files exist or form a usable pair. Gateway startup validates configured or discovered signing bundles. Sandbox creation checks the selected driver’s launch-signing requirement before image preparation.
To validate the exact daemon arguments that a wrapper will pass, place them after
-- instead of using --path:
Debian and Ubuntu run preflight from the systemd user unit before local certificate
generation. The unit still loads the gateway.env environment file and starts the
gateway with no configuration arguments. snap replays the exact effective daemon
arguments through preflight. It gives a nonempty OPENSHELL_GATEWAY_CONFIG
precedence; otherwise it validates and passes its canonical service-specific
path only when that path exists in the filesystem. The legacy system service
uses $SNAP_COMMON/gateway.toml; the user service uses
$SNAP_USER_COMMON/.config/openshell/gateway.toml. A broken
symlink is therefore rejected instead of being treated as absent.
Package startup does not modify an operator-owned v1 file. Back it up, follow Migrate to schema version 2, then validate the result explicitly before restarting the service:
Check local VM host tools
For an explicitly selected local vm driver, preflight also checks a formatter (mke2fs or mkfs.ext4), debugfs, and e2fsck. Install e2fsprogs 1.43 or newer with your operating system’s package manager. OpenShell does not install or manage these host dependencies.
For example, on macOS:
Run preflight with the account, configuration, working directory, and environment intended for the gateway. A successful check in an interactive shell does not check a service with a different PATH. For a service whose environment uses a private installation, reproduce its configured path explicitly:
Replace the executable and configuration paths with your installation’s paths, and run this command as the service account. Preflight and VM image operations search inherited PATH entries, then the existing e2fsprogs sbin and bin directories under /opt/homebrew/opt/e2fsprogs and /usr/local/opt/e2fsprogs. They prefer mke2fs and try mkfs.ext4 only when mke2fs is absent. A selected file that cannot run is an error; fix that installation or the service’s PATH before rerunning the command.
The command reports each selected executable path and version. Each tool receives only -V, with a five-second deadline and an 8 KiB output limit per stream. Missing, non-executable, outdated, or failing tools return a nonzero exit status with corrective guidance and the selected tool’s error. The checks create no gateway state or images and do not start a driver or VM. Version checks confirm the installation; they do not test image creation or filesystem recovery.
Other drivers do not require these VM tools. A VM configuration table alone does not select the VM driver. When a remote driver socket is configured, preflight reports that host tool checks were not performed; run the check on that host in the driver service’s environment with a local VM configuration.