Skip to main content

Configuration

ProtocolConfig

Only two fields are required: appId and profile.
userId was removed in v0.21.0. It is replaced by profile, which is not the same field renamed. profile selects which stored identity this instance runs as and never leaves the device. Your identity on the wire is a self-certifying off1… address the SDK derives from an identity key it mints for itself. Read it with localAddress() or the identity_ready event. An app cannot choose it.See Identity & Addressing for the migration.

appId

Application identifier. Combined with profile it forms the storage namespace.

profile

Local profile selector: which stored identity this instance runs as. The storage namespace is SHA-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.
Setting nostr.sealingEnabled: false puts the entire protocol envelope (both addresses, app id, metadata map, content type, and timestamp) in relay-readable cleartext, permanently. It exists only to reach pre-sealing peers. Leave it on.

EncryptionConfig

Controls MLS-based end-to-end encryption. Encryption is enabled and fail-closed by default.
requireEncryption defaults to true. To deliberately operate in plaintext (an open broadcast mesh with no provisioned key storage, say) you must opt out explicitly. Every plaintext send then emits a security_warning event with the PLAINTEXT_SEND reason code, once per peer.

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.
enforceAdminCommits is a decision about partition risk, not a hardening tweak. Leaving it off does not mean unauthorized changes go unnoticed; they are applied and reported via group_unauthorized_membership_change. Turning it on means refusing the MLS merge, so this device’s epoch stays behind every member that accepted it, and MLS cannot heal that: the app has to re-invite. Enable it only for a closed deployment that controls role distribution, and never on part of a fleet.

DorsConfig

Controls transport switching behavior. Can also be changed at runtime with updateDorsConfig().

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.
Zero is rejected for maxTrackedMessages and retentionTimeSecs. The three runtime updaters (updateAckConfig, updateRetryConfig, updateDedupConfig) are fallible and throw on invalid input.

PathConfig

FileTransferConfig

TelemetryConfig

Passed to installTelemetrySink() rather than to the constructor.
Omitting 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.