Peer sync / server mode

Admin

Desktop only. Server mode syncs configuration between desktop installations – not content. The concept is explained in Connections / peer-server sync, the multi-user variant in Multi-user – desktop server mode.

Goal

Keep multiple desktop workstations consistent: one host provides the configuration (model providers, MCP servers, system prompts, Skills names, System settings), clients adopt it. What is not synced: content, mailboxes, agents, MCP OAuth tokens.

Two topologies

Desktop ↔ desktop (LAN): the host runs as a ServerHost (embedded server); clients pair via a 6-digit code over mDNS discovery; secured by a self-signed certificate with fingerprint pinning. The code is single-use, ~10 minutes.
Desktop ↔ central API (internet/VPN): the client fetches the configuration from /api/admin/bootstrap; authentication via OTP-JWT, CA-trusted certificate.

Add a peer

LAN (ServerHost): Host: enable server mode; when a user is created, a pairing code is issued (with hostname + fingerprint). Client: in the setup wizard select the host via discovery, confirm the fingerprint, enter the code → the configuration is adopted (initial pairing = full overwrite).

API mode: Client: store the server URL, test the connection, enable client mode; after a brief notice a sign-out occurs, then the configuration is pulled (upsert, local additions are preserved).

Re-sync the configuration

In the Connections tab: Refresh configuration loads the current config and shows a diff (key · local · server, with (new)/(removed)). After review, Apply changes. In API mode, syncing can additionally happen automatically on mode change/after login.

Remove a peer

LAN: turn off server mode on the host or revoke the code – the pairing expires.
API: reset the client to Standalone or disable server mode – the JWT is discarded.

Behavior when the host is unreachable

Local sign-in remains possible (the pairing user is mirrored locally). A sync fails, but the most recently adopted configuration stays valid. Note: in API mode the client has no local SMTP – if the central API is offline, OTP delivery may fail; in LAN mode SMTP was handed over during pairing (local OTP fallback possible).

Security

During the LAN sync, the host’s TLS fingerprint is pinned; if the server certificate differs, the handshake fails (protection against man-in-the-middle). Scheduled agents only run while the desktop app is open.

Verification

After the sync the diff shows no open discrepancies; the clients’ models/MCP servers match the host — with one deliberate exception: the PII trust checkbox of an MCP server the client already knows is decided by the client itself. → Export, import and pairing