Skip to main content
The SDK is usually embedded: one application, one process, one engine. The local API is the other shape. One process owns the engine and serves any number of local applications over a socket, so a host where several programs need the same identity, peers and documents runs one node instead of several. Each application speaks JSON-RPC 2.0 over a WebSocket, declares which application it is, and calls the engine’s methods and receives its events by name. The Python package ships the reference server as the offline-protocol-service command (module offline_protocol_sdk.local_api), from v0.28.0. Install the package from PyPI first; see Python and Linux gateways.

Guarantees for every client

  • The server owns the engine. It runs the loop, drains inbound messages, starts and stops. No client can call process(), receive_message() or stop().
  • A connection speaks for one application. The first request is hello with an app_id. Every message that connection sends is stamped with it, and an inbound message stamped with it reaches only connections that declared it.
  • The socket is the authorization boundary. Whoever can open the Unix socket, or holds the launch token on TCP, is one of the operator’s applications. The server does not tell one local process from another.
  • Events are the engine’s JSON, unchanged. A client that handles message_received from the embedded SDK handles the same object here.

Start the service

The service runs over the built-in file stores, so a host with no secret service needs only two directories and a key:
config.json holds the ProtocolConfig fields by name, with enum values spelled as in the interface definition:
--listen and --peer drive the peer-stream transport when the configuration enables it (--peer takes host:port or off1...@host:port). --gateway HOST:PORT names the gateway daemon when the configuration enables reticulum (default localhost:4242). --keyring uses the platform keyring instead of the file stores. Run offline-protocol-service --help for the full list. To run the service in a container, use the published image ghcr.io/offline-protocol/offline-protocol-service:0.34.0 for linux/amd64 and linux/arm64, pinned by digest. It maps environment variables to these flags and keeps the identity on a volume; see run it in a container for the tags and what the host must grant.

Transports the service starts

From v0.29.0 the service starts every transport the configuration enables and the host can run: --lan advertises the host over DNS-SD and dials every other host that advertises the same service type, so hosts on one segment find each other with no --peer list. It needs the lan extra (pip install 'offline-protocol-sdk[lan]') and multicast DNS, so a container must share the host’s network. A transport that fails to start is logged and stays stopped while the others run; the service fails only when none starts. Each transport has 30 seconds to start. A flag the configuration cannot honour is refused at start: --listen, --peer or --lan without wifi_direct_enabled, --relay without internet_enabled, a --relay value that is not a ws:// or wss:// URL with a host, and a --relay-token-env variable that is not set. From v0.34.0 the service checks the socket path before the engine starts. A socket directory that is not this user’s or that group or others can read, a path that exists and is not a socket, and a path longer than the platform allows (104 bytes on macOS, 108 on Linux) raise SocketPathError, a ValueError, and the command exits with a one-line --socket: message. A directory the service creates is made 0700; it does not narrow one it did not create. The local API never binds a non-loopback address. To reach the API across a network, put a reverse proxy with its own authentication in front of it. GET /health on either carrier returns the server name and version, the API version and the carrier. There is no other HTTP path: a single call is a connection that sends hello, one request, and closes.

Talk to it

Every request is a JSON-RPC 2.0 object with an id. Every event is a notification whose method is event and whose params is the event object.
This Python client declares an application, narrows its events, and edits a replicated document. It needs only the websockets package the SDK already depends on.
  • Sending. Call the engine’s methods by name with the parameters the interface definition gives them, for example send_message with recipient, content and priority. It returns the message ID. The message_sent and message_delivered events for that ID come back to the sending connection only. Watch for message_undeliverable as well.
  • Subscribing. After hello a connection receives every event routed to its application. subscribe with types narrows that; subscribe with "all" resets it.
  • Held messages. An inbound message for an application with no connected client is held, up to 256 per application ID, and delivered after the next hello under that ID. Delivery is at least once, so deduplicate on message_id.
  • Documents and services. The replicated document store is reachable as data.* methods and mesh services as services.*, including from v0.32.0 the subscription methods such as services.subscribe_service and services.publish_service_update. The server routes service_update_received and service_subscription_changed to the client that subscribed, and lets only the application that registered a service publish to it, clear it, set its checkpoint or set its policy. A write carries a tagged value; a read returns plain JSON. With the data layer off, every data.* call answers DataDisabled.
  • Errors. A failed call is a JSON-RPC error whose data.variant is the engine’s ProtocolError variant. Switch on the variant, not the number. A method before hello is InvalidState; a refused token, space or method is PermissionDenied.
Platform operations (driving a radio, attaching storage, feeding frames, running the loop, owning telemetry) are not on the wire, because the server owns them.

Call services over plain HTTP

--http 127.0.0.1:8080, with the http extra, starts the HTTP front in the same process. It lets an application that does not use the SDK call a service on another device with an ordinary HTTP request to <service>.<device>.offline.protocol.internal, carried inside an end-to-end encrypted message. The front connects to this server under the application ID offline-protocol-http-front; a policy file that names any application must list that ID too. See HTTP front.

Check what the network did

offline-protocol-verify, installed with the package from v0.29.0, drives the service on the host it runs on and waits for the engine’s own events, so a check passes or fails on what the engine reports.
Each command prints JSON lines and exits 0 on a pass, 2 when its time ran out and 1 on a terminal failure. A receipt the engine emits while no client of the application is connected is not held, so wait for it with send --await, or start await or watch on the sender before the recipient can answer; both print subscribed on standard error once they are listening. Every verifier declares the application ID offline-protocol-verify unless --app-id says otherwise, and the sender and recipient must declare the same one. The SDK’s offline-first example uses the verifier to run store and forward, a sender restart, delivery through a middle device to one the sender never met, and delivery while the sender is off, on three containers.

Policy file

With no policy, any well-formed application ID is accepted. --policy policy.json adds rules per application ID:
Once spaces or denied names any application, an ID that no section names is refused at hello.

Application IDs on the wire

The ID a client declares is stamped on each message it sends, in place of the configured app_id, and message_received and file_received report it on the receiving node. It changes only the stamp, never the storage namespace or the MLS session. The ID is cleartext and unsigned on the wire: route on it, never authorize on it. The same per-send ID is available without the service through SendMessageOptions and MediaSendOptions in Python and Rust, and the appId option of sendMessage and sendMedia in React Native.

Reference