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()orstop(). - A connection speaks for one application. The first request is
hellowith anapp_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_receivedfrom 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 anid. Every event is a notification whose method is event and whose params is the event object.
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_messagewithrecipient,contentandpriority. It returns the message ID. Themessage_sentandmessage_deliveredevents for that ID come back to the sending connection only. Watch formessage_undeliverableas well. - Subscribing. After
helloa connection receives every event routed to its application.subscribewithtypesnarrows that;subscribewith"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
hellounder that ID. Delivery is at least once, so deduplicate onmessage_id. - Documents and services. The replicated document store is reachable as
data.*methods and mesh services asservices.*, including from v0.32.0 the subscription methods such asservices.subscribe_serviceandservices.publish_service_update. The server routesservice_update_receivedandservice_subscription_changedto 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, everydata.*call answersDataDisabled. - Errors. A failed call is a JSON-RPC error whose
data.variantis the engine’sProtocolErrorvariant. Switch on the variant, not the number. A method beforehelloisInvalidState; a refused token, space or method isPermissionDenied.
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 configuredapp_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
- Local API guide and specification chapter, with every method, event and error.
- Python client example over the Unix socket or TCP.
- HTTP front chapter and the service container image, published as
ghcr.io/offline-protocol/offline-protocol-serviceand built frombindings/python/docker. - Node client example for Node 22 or later with no dependencies, over TCP with the token file.

