OfflineProtocol requires appId and profile. Here appId is a mesh app identifier: any string you choose, not the portal App ID (app_…), and no account is needed. Other settings are optional. Keep those two identifiers stable across normal restarts to reopen the same identity and state.
v0.31.0 defaults
These defaults target the React Native v0.31.0 binding, not example overrides. The Rust core enables its Wi-Fi and internet slots by default; the React Native constructor explicitly defaults both off. Configure transports explicitly when moving between bindings.
See limits and capacity for hard ceilings, and the release source for configuration defaults. Retention bounds must cover your expected disconnection duration.
The pending-decryption process TTL restarts with the process. Its persisted copy has a separate 7-day maximum age; it is not the outbound outbox. Configure retention around the specific queue your workflow uses.
ProtocolConfig
appId is the mesh app identifier you choose; with profile, it scopes local stored state. It is not the portal App ID. Neither replaces the device’s off1… address. userId was removed in v0.21.0 and path was removed in v0.23.0.
Serve several applications from one identity
From v0.28.0 a send can name the application it is for. One instance that serves several local applications behind one identity passesappId to sendMessage or sendMedia; that ID is stamped on the message, or on every chunk of the transfer, in place of the configured one.
message_received and file_received carry the sender’s app_id. The per-send ID changes only the stamp on that frame, never the storage namespace, the MLS session or the BLE app tag, and the acknowledgement keeps the configured ID. It is cleartext and unsigned on the wire: route on it, never authorize on it. An invalid ID fails the call with InvalidArgument before anything is queued. A single-app integration never sets it. For a host process serving several applications, see the local API service.
TransportsConfig
BLE is enabled by default. Internet relay, Wi-Fi, Reticulum and Nostr are configured separately. Enable only the paths your deployment provides. See platform compatibility and Reticulum and Nostr.wifiDirect: { enabled: true } starts the phone peer-stream transport from start() in v0.31.0. On Android it also advertises and browses on the Wi-Fi network the phone is on, from v0.29.0, so it meets iPhones and Python hosts there. On Android 10 and later, autoAccept: true lets the SDK form the Wi-Fi Direct group itself, with no system dialog; it is off by default. groupOwnerIntent is deprecated and unused. See phone Wi-Fi peer streams.
ble.advertiseNodeHash (Android only, default false, from v0.31.0) carries an 8-byte digest of the device’s address in its Bluetooth LE scan response, so an iPhone can attribute peer_rssi readings to that Android phone. The digest never changes, so any scanner in range can follow the phone across Bluetooth address rotation, and anyone who knows its address can recognise it without connecting (threat model R29). Turn it on only for a proximity feature that needs iPhones to read Android phones.
internet.serverAddress is the relay WebSocket URL. Supply the signed-in user’s OfflineID session token as authToken; a portal key is not a relay credential. For the hosted relay, use wss://relay.offlineprotocol.com; see relay access to enable it.
EncryptionConfig
Keepenabled and requireEncryption on for application messages. autoKeyExchange establishes sessions with discovered peers; it does not authorize their business actions. Pending encryption work has capacity and lifetime limits. A plaintext control channel, including service discovery, remains distinct from encrypted application messages.
encryptServiceMessages (default true, from v0.29.0) seals service request and response bodies inside the 1:1 MLS session toward a peer that advertises support, once the session is confirmed. Toward other peers, and before the session confirms, bodies stay signed plaintext. false stops this device advertising, recording and sealing; a sealed frame from a peer still reaches your service handlers. A sealed body is about 1.34 times larger on the wire.
Setting encryption.enabled: false disables the derived encryption flags, DataStore and Nostr. Do not use it to bypass session initialization failures.
security.controlFreshnessEnforced applies clock-based freshness checks to control messages. An incorrect verifier clock can reject valid frames; synchronize device time and surface freshness failures.
ReliabilityConfig
Configure acknowledgment timeout, retry policy, deduplication and outbox lifetime against your workload. Queue overflow and expiry produce failures; they do not provide unlimited offline retention.message_undeliverable is non-terminal and can repeat while a recipient is unreachable.
GroupConfig
Group membership scopes encrypted group communication. Admin-commit enforcement changes partition behaviour: enable it consistently only when the deployment controls membership and recovery. Relay broadcast depends on both configuration and the relay’s supported delivery-report capability.DorsConfig
DORS selects among eligible configured transports. Hysteresis and cooldown control switching. A routing preference cannot create a missing radio bridge or reachable peer.RelayConfig
Device relaying and a hosted internet relay are different.relay controls participation in mesh forwarding. Its relayPriority values are never, auto and always; runtime getters and setters use never, auto and always as well. The legacy low, medium and high spellings are accepted on input only.
FileTransferConfig
Set file size and chunk limits for the qualified transport. Keep the source bytes available for any application resend requested after interruption.DataConfig
data.enabled controls replicated documents and defaults to true in the v0.31.0 Rust core. The default comment in that release’s TypeScript declaration (false) is stale. Set enabled explicitly when your deployment requires a fixed policy.
CustodyConfig
custody lets this device hold a neighbour’s replicated-document frames for hours while the recipient is away. It is off by default and applied at construction. See custody for the options, quotas and risks.
TelemetryConfig
Configure hosted telemetry throughenableTelemetry, not the protocol constructor:
appId is the portal App ID (app_…), not the constructor’s mesh app identifier. See Enable SDK telemetry.
setTelemetryEnabled(false) stops new collection while previously queued records can drain. disableTelemetry() shuts the uploader down after its final flush. flushTelemetry() requests an upload. The pre-v0.26 sink and polling APIs have been removed.
If your app calls enableTelemetry, use v0.30.0 or later. From v0.30.0 the uploader trusts only the certificate roots of the authorities that issue the telemetry endpoint’s certificate; 0.26.0 to 0.29.0 trusted the whole bundled Mozilla set, including a root withdrawn after the October 2026 eMudhra key compromise. See upgrade from v0.29.