Gateway FabricGateway Fabric CLI and configuration

Gateway Fabric CLI and configuration

Configure Gateway Fabric storage, carrier selection, listeners, security limits, and environment overrides.

Select the TOML configuration with -c or --config. Environment overrides apply after the file. Use absolute filesystem paths for managed services.

Commands

atlas-gateway-fabric accepts the commands below.

CommandEffectLimit
--versionPrints the executable versionDoes not inspect running service state
initLoads or creates the durable identity and prints its DIDDoes not provision organization authority
statusParses and prints configuration, then exitsDoes not contact the running process or check storage
startValidates uplink selection, loads provisioned credentials, and starts the runtimeRequires the matching identity and credential bundle

status prints the database URL. Redact embedded credentials before sharing output. Parsing success does not establish startup validation or listener reachability.

Read-only maintenance commands inspect the configured database.

scan-ontology prints a JSON classification report and exits unsuccessfully if stored values block tagged payload readers.

member-grant-dry-run reports what the member-grant reconciliation would sign. It signs nothing and runs no migration.

Run maintenance only with authorized database access and the matching identity and encryption settings.

Put iroh network fields directly under [transport]. Do not nest them under [transport.iroh]. The flattened transport table does not reject every unknown key, so a misplaced table can leave defaults active.

A bind address is not an advertised URL. Private DNS, TLS termination, and WebSocket upgrade forwarding are separate configuration concerns.

Fields and defaults

TableFieldDefault or requirement
gatewaynameRequired string
gatewaydata_dir./data/atlas-gateway-fabric
gatewayallow_plaintext_keyfalse
storagedatabase_urlRequired SQLite or PostgreSQL URL
storagemax_connections75, PostgreSQL pool limit
storageacquire_timeout_secs10, PostgreSQL pool acquisition timeout
transportrelay_urls, pkarr_urls, dns_originsEach []
transportdht_enabled, ipv4_onlyEach false
transportmdns_enabledtrue
transport.uplinktransportws
transport.wsenabledfalse, enable explicitly for the ws uplink
transport.wsbind_addr0.0.0.0:9443
transport.wsmax_concurrent_handshakes256
transport.wshandshake_timeout_ms5000
transport.wsenforce_ucan_root_of_trusttrue
transport.wsrequired_client_features[]
transport.wssession_summary_log_enabledfalse
healthenabled, bind_addrtrue, 0.0.0.0:8080
metricsenabled, bind_addrfalse, 0.0.0.0:9092

Health defaults apply even when its table is absent. Use explicit restricted binds rather than relying on defaults.

Operational listeners use [transport.ws] and [transport.mqtt]. Fields named endpoint, ws_url, ws_bind_addr, or invite_token_path in [gateway] do not configure those listeners or provision credentials. Omit them.

Select ws and enable its listener. An omitted WebSocket table defaults to disabled even though the default uplink is ws. That combination parses but fails startup.

The values quic, mqtt, and rest are not usable selected uplink acceptors in this executable. Startup rejects them with a feature-disabled or acceptor-unavailable error. Compiling a selector feature does not create its missing acceptor.

This selector is distinct from the running QUIC networking and the optional MQTT broker. Enabling MQTT does not expose REST resources or a control-uplink service.

required_client_features sets a client capability floor. A missing required claim returns ERROR_KIND_UNSUPPORTED_CLIENT before the WebSocket envelope handshake completes. A feature claim is not authorization. Keep root and per-scope capability checks enabled. Apply a floor only when the intended clients support it.

MQTT broker

Field under transport.mqttDefaultMeaning
enabledfalseStarts no broker until enabled
bind_addr0.0.0.0:1883Broker socket
connect_freshness_secs30Signed CONNECT token freshness window in seconds
max_segment_size10485760Retained bytes per commitlog segment
max_segment_count10Segments per topic filter
nonce_ledger_identity_capacity4096Distinct identities tracked for nonce replay protection
refuse_connect_under_client_feature_floorfalseRefuses all MQTT CONNECTs under an active feature floor when enabled
tlsAbsentOptional server TLS configuration

MQTT v4 retention is size-bounded, not time-bounded. Default commitlog retention is 100 MiB per topic filter, not a total disk bound or a live-sample replay guarantee.

The broker listener is plaintext unless TLS is configured. Signed CONNECT identity does not provide wire confidentiality by itself. The rustls backend uses backend, certpath, and keypath under transport.mqtt.tls and requires protected certificate files.

capath is optional. A native_tls backend uses pkcs12path and pkcs12pass and requires matching compiled support. Keep passwords out of shared TOML. Verify the selected backend and network protection before admitting remote clients.

MQTT v4 has no equivalent client feature-claim field. With refuse_connect_under_client_feature_floor = false, CONNECT admission remains independent of that floor. With true, all MQTT peers are refused while a floor is set. This is a deployment-wide policy, not an individual-client filter.

Database settings

sqlite:fabric.db resolves beneath gateway.data_dir and uses identity-derived encryption. sqlite:/var/lib/atlas-gateway-fabric/fabric.db selects an absolute path. sqlite::memory: is volatile development storage, not a deployment database.

PostgreSQL URLs begin with postgres:// or postgresql://. They require an artifact with PostgreSQL support and valid protected database credentials. Use the pool fields to bound database connections and acquisition waits.

Preserve the exact database URL mode recorded in a provisioned or restored recovery set. The URL prefix participates in encryption-mode selection. Do not change it to repair a decryption failure.

Keep ATLAS_PLAINTEXT_DB absent in encrypted deployments. Its presence selects plaintext development storage even when its text value is false.

Environment overrides

Use ATLAS_GATEWAY_FABRIC__SECTION__FIELD, with another double-underscore segment for each nested table. The device-key passphrase uses the separate ATLAS_GATEWAY_KEY_PASSPHRASE variable. Supply it through a secret manager or protected service environment.

There is no [logging] table. Inspect effective configuration privately, then verify startup and dedicated health independently.