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.
| Command | Effect | Limit |
|---|---|---|
--version | Prints the executable version | Does not inspect running service state |
init | Loads or creates the durable identity and prints its DID | Does not provision organization authority |
status | Parses and prints configuration, then exits | Does not contact the running process or check storage |
start | Validates uplink selection, loads provisioned credentials, and starts the runtime | Requires 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
| Table | Field | Default or requirement |
|---|---|---|
gateway | name | Required string |
gateway | data_dir | ./data/atlas-gateway-fabric |
gateway | allow_plaintext_key | false |
storage | database_url | Required SQLite or PostgreSQL URL |
storage | max_connections | 75, PostgreSQL pool limit |
storage | acquire_timeout_secs | 10, PostgreSQL pool acquisition timeout |
transport | relay_urls, pkarr_urls, dns_origins | Each [] |
transport | dht_enabled, ipv4_only | Each false |
transport | mdns_enabled | true |
transport.uplink | transport | ws |
transport.ws | enabled | false, enable explicitly for the ws uplink |
transport.ws | bind_addr | 0.0.0.0:9443 |
transport.ws | max_concurrent_handshakes | 256 |
transport.ws | handshake_timeout_ms | 5000 |
transport.ws | enforce_ucan_root_of_trust | true |
transport.ws | required_client_features | [] |
transport.ws | session_summary_log_enabled | false |
health | enabled, bind_addr | true, 0.0.0.0:8080 |
metrics | enabled, bind_addr | false, 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 the client-facing uplink
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.mqtt | Default | Meaning |
|---|---|---|
enabled | false | Starts no broker until enabled |
bind_addr | 0.0.0.0:1883 | Broker socket |
connect_freshness_secs | 30 | Signed CONNECT token freshness window in seconds |
max_segment_size | 10485760 | Retained bytes per commitlog segment |
max_segment_count | 10 | Segments per topic filter |
nonce_ledger_identity_capacity | 4096 | Distinct identities tracked for nonce replay protection |
refuse_connect_under_client_feature_floor | false | Refuses all MQTT CONNECTs under an active feature floor when enabled |
tls | Absent | Optional 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.