Configuration
ProtocolConfig
Only two fields are required:appId and profile.
appId
Application identifier. Combined withprofile it forms the storage namespace.
profile
Local profile selector: which stored identity this instance runs as. The storage namespace isSHA-256(domain ‖ 0x00 ‖ appId ‖ 0x00 ‖ profile). An app hosting
several accounts gives each its own value; an app hosting one can pass a constant such as
'default'.
If you are migrating from userId, pass the same string through as profile. That keeps
you in the same storage namespace.
binaryWireEnabled
Kill switch for the compact binary wire codec on mesh hops (default:true). Negotiated per
peer via the key package; decoding of inbound binary frames is always on. Disabling stops
advertising and emitting, so both directions fall back to JSON framing. It is the hop-local
sibling of encryption.compactEnvelopeEnabled.
TransportsConfig
Five transports are available. BLE is on by default; the rest are opt-in.TransportType is 'ble' | 'internet' | 'wifiDirect' | 'reticulum' | 'nostr'.
Reticulum requires external infrastructure (a running Reticulum daemon, an RNode radio, or a
network gateway). Nostr requires at least one relay URL. Both are disabled by default for
that reason. See Reticulum & Nostr.
EncryptionConfig
Controls MLS-based end-to-end encryption. Encryption is enabled and fail-closed by default.GroupConfig
relayEnabled controls whether groups register with the relay server. Registration is what
invite links resolve against, so leave it on unless the app never uses relay group features.
relayBroadcastEnabled lets a relay-synced group send one O(1) relay broadcast instead of
per-member fan-out. The flag alone never selects the broadcast: the connected relay must also
advertise the group_delivery_v3 capability, whose settled per-recipient delivery report is
what gives the broadcast a delivery contract. Members the relay did not reach are re-sent
per-member automatically. See
group_message_delivery_report.
DorsConfig
Controls transport switching behavior. Can also be changed at runtime withupdateDorsConfig().
RelayConfig
relayPriority uses 'never' | 'auto' | 'always' here, but the runtime methods
setRelayPriority()/getRelayPriority() use
'low' | 'medium' | 'high'. The SDK normalizes config values when applying them:
never → low, auto → medium, always → high.NetworkConfig
ReliabilityConfig
outboxMaxLifetimeMs bounds store-and-forward outbox entries. After a restart it also prunes
restored outbox entries and persisted media transfer descriptors. Expiry is terminal: a
message_failed event with reason
"Outbox lifetime exceeded" (capacity eviction reports "Outbox capacity exceeded"). An
entry older than 4× this lifetime in total is dropped terminally.
pendingMessageMaxLifetimeMs is how long a message may wait for MLS session establishment
before a terminal message_failed is emitted.
PathConfig
FileTransferConfig
TelemetryConfig
Passed toinstallTelemetrySink() rather than to the
constructor.
metricsCadenceMs yields the default cadence. There is currently no way to disable
periodic emission through this config. Push-only integrations should pass
enablePollQueue: false to skip the per-emit JSON envelope build.
Full example
Next: API Methods
Explore all available methods for messaging, encryption, groups, and more.