Switches version; unavailable chapters open its introduction.

Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sync Across Two Machines

contextdb syncs by dialing a key, not by connecting to a broker. One machine runs a hub; any number of edges dial it directly using a ticket the hub prints — no message broker, no port-forwarding, and (on a LAN) no external infrastructure at all.

You need the contextdb CLI and the contextdb-server binary on the machines involved; see Install. The .sync meta-commands and auto-sync are specified in the CLI Reference; the recipe-shaped depth — enrollment, delete propagation, conflict classes — is in skills/sync/SKILL.md.

Start the hub

On machine A, run a sync hub — a contextdb-server process the edges dial into:

contextdb-server --db-path hub.db --tenant-id demo

A hub requires a durable store: --db-path names the file it keeps its state in.

On startup it prints an enrollment ticket and the exact command an edge runs to connect (substitute your own database path for <client-db-path>):

enrollment ticket: <ticket>
To connect a client, run:
  contextdb <client-db-path> --write --sync-endpoint <ticket> --tenant-id demo

The ticket is the hub’s cryptographic identity — dial-by-key. Whoever holds it can dial the hub directly, wherever it is, including from behind NAT (the edge dials out; nothing needs to be reachable on machine A). The hub only serves — you don’t type SQL at it; your data lives on the edges that dial in. For scripting, three flags skip the banner: --show-ticket prints the bare ticket and exits, --ticket-file <path> writes it to a file, and --json emits a JSON object with enrollment_ticket, dial_command, endpoint, and tenant_id.

Treat the ticket as sensitive bearer material, not a public identifier. There is no allowlist — anyone who obtains the ticket can enroll and sync with the hub until the hub’s identity changes. Keep any file it’s written to (--ticket-file, --json output, shell history) out of version control and restrict its file permissions. If a ticket leaks, rotate by re-keying the hub — delete hub.db.fabric-identity.key and restart, which changes the hub’s identity and invalidates every previously issued ticket.

Connect two edges

On each edge machine, paste the ticket, giving each its own database file:

# machine B
contextdb edge-1.db --write --sync-endpoint <ticket> --tenant-id demo
# machine C
contextdb edge-2.db --write --sync-endpoint <ticket> --tenant-id demo

The ticket is pinned to each edge’s identity key on first connect, so later reconnects are authenticated the same way. Two machines on one LAN sync with nothing running in the middle — no cloud relay or other third party.

Converge in both directions

Sync is push/pull, driven from the REPL with .sync meta-commands. On edge 1, create a small example table (decisions is a table you define — see the README), insert a row, and push:

-- on machine B (edge 1)
CREATE TABLE decisions (id UUID PRIMARY KEY, status TEXT NOT NULL, reasoning TEXT);
INSERT INTO decisions (id, status, reasoning) VALUES ('750e8400-e29b-41d4-a716-446655440020', 'active', 'captured on edge 1');
.sync push

On edge 2, pull and read it back — the schema and the row both arrive:

-- on machine C (edge 2)
.sync pull
SELECT * FROM decisions WHERE id = '750e8400-e29b-41d4-a716-446655440020';
-- returns the row captured on edge 1

Now the other direction. Insert a row on edge 2, push, and pull it onto edge 1:

-- on machine C (edge 2)
INSERT INTO decisions (id, status, reasoning) VALUES ('850e8400-e29b-41d4-a716-446655440030', 'active', 'captured on edge 2');
.sync push
-- on machine B (edge 1)
.sync pull
SELECT * FROM decisions WHERE id = '850e8400-e29b-41d4-a716-446655440030';
-- returns the row captured on edge 2

Both edges now hold the same two rows, converged through the hub. .sync status reports what’s pending in each direction before you push or pull. Table direction and conflict behavior are durable CREATE TABLE/ALTER TABLE declarations (SYNC ... and SYNC CONFLICT ...), not session commands. The sync meta-commands and auto-sync are in the CLI Reference; the wire protocol is covered in the Architecture doc’s Sync section.

Restart durability

The hub keeps its identity in <db-path>.fabric-identity.key next to the database file (here, hub.db.fabric-identity.key). Restarting the hub reuses that key, so the same ticket — and every edge already pinned to it — keeps working. Back this file up like a credential; never commit it to source control.

Memory accounting

Fetching delivery outcomes is charged to the reading store’s declared reader memory on both sides. Each page stops at the reader’s cursor_page_bytes (and never exceeds the transport’s 64 MiB frame), and a fetch the reader cannot fund is refused with a typed memory refusal before its bytes are allocated.

Two things sit outside this accounting: the Iroh networking stack’s own buffers and connection state, and tracing output. Each accepted connection also keeps one small fixed task frame, bounded by the hub’s pre-admission connection limit (128 by default).

Manifested application units

The enrollment ticket authenticates the hub; application-table policy is bound separately. First declare it with contextdb --write hub.db; then call the edge’s SyncClient::bind_application_table_policy before creating those tables. The complete runnable recipe includes both steps.

For tenant-governed event tables, declare policy on the hub, bind it through the edge’s authenticated SyncClient, and install matching DDL before recording units. Register each manifest in its root’s write transaction. Manifests use the ordinary push and its existing oversized-unit staging transport. Every committed column travels with its row, including a large body the edge store keeps on disk rather than in memory.

A durable outcome, rather than a push watermark, ends that unit’s pending obligation; fetch recovers lost acknowledgements without applying rows again. Refused rows stay on the edge and their diagnostic keys identify them.

An ordinary status exchange verifies one hub-signed prefix checkpoint against the hub image. A failed verification is an error. A restored image that lost acknowledged custody receives a new incarnation; unrelated writes or later purges cannot mask that loss. This also works with a declared snapshot taken before the first binding: the edge automatically rebinds, old outcomes become pending, and unchanged local rows are offered again. Missing declarations remain a typed policy refusal. Reopening the current image preserves its incarnation and valid credit.

See tenant policy and event custody for the SQL, local-discard modes, metadata inspection, and atomic purge delivery to independently keyed node-local tables. Operator-held backups from before a purge remain outside the engine’s erasure reach: restore one only with the documented re-purge recovery.