Skip to content

anchor-peer-deployment.md

Latest commit

 

History

History
153 lines (114 loc) · 6.77 KB

anchor-peer-deployment.md

File metadata and controls

153 lines (114 loc) · 6.77 KB
Raw

Anchor-peer deployment with Sharing domains

An anchor peer is a normal codemem peer that happens to have high uptime. It is useful as a stable sync backstop for laptops, but it is not a coordinator, gateway, quorum node, backbone tier, or special protocol role.

The rules are the same as for every other peer:

  • The peer has its own device key and local SQLite database.
  • It only receives memories for Sharing domains where it has explicit scope membership.
  • Project include/exclude filters can narrow what it receives, but they cannot grant access.
  • The coordinator can help devices discover the anchor peer, but memory payloads still move directly peer-to-peer.
  • If the anchor peer is revoked from a Sharing domain, it stops receiving future sync for that domain. Already-copied data on its disk is not erased.

Deployment shapes

Solo local use

No anchor peer is needed. One device writes to its local SQLite database. Keep unknown projects local-only until you intentionally map them to a Sharing domain.

Personal multi-device sync

Use a personal Sharing domain, for example personal:owner, and grant only your own devices to it. A home server or small VPS can join that personal domain as an anchor peer if you want memories available when laptops sleep.

Recommended shape:

  • laptop: member of personal:owner
  • desktop: member of personal:owner
  • always-on anchor peer: member of personal:owner
  • coordinator: optional discovery plane, not a data path

Small team VPS

For a small team, run one always-on peer on a VPS and grant it only to the team domains it should hold, such as acme-work. Do not grant it to personal or client domains unless it intentionally needs those memories.

Recommended shape:

  • teammates' laptops: members of acme-work
  • VPS anchor peer: member of acme-work
  • optional OSS domain: separate oss-codemem membership if the VPS should hold OSS memories too
  • coordinator: can run on the same VPS for discovery/admin, but it remains separate from the anchor peer's local memory database

Organization with three always-on peers

For higher availability, run three always-on peers. They are still three normal peers, not a quorum cluster. Each peer has a local SQLite database and syncs via the same peer protocol as laptops.

Recommended shape:

  • three k8s pods or VMs running codemem as regular peers
  • each peer has explicit membership in the org/team Sharing domains it should hold
  • each peer has durable local storage if you want it to survive restarts without a full re-bootstrap
  • laptops sync with whichever peer is reachable; the always-on peers converge with each other through normal peer sync

If one always-on peer dies, the remaining peers continue holding their local copies. A replacement peer should be enrolled, granted the intended Sharing domains, and bootstrapped from existing peers.

Storage and backups

Anchor peers are local-first peers, so restoring their identity requires one coherent backup set:

  • the effective SQLite database selected by --db-path or CODEMEM_DB
  • <keys-dir>/device.key, the secret Ed25519 private key
  • <keys-dir>/device.key.pub, the corresponding public key
  • the effective config selected by --config, CODEMEM_CONFIG, or the configured runtime root, or equivalent environment settings that select the same database, key directory, coordinator, and listener configuration

Protect the database and config as sensitive data and the private key as a credential. Never publish the private key, coordinator secrets, invite tokens, or an unredacted config snapshot as diagnostic artifacts.

Use durable storage for the complete set. Prefer a filesystem or volume snapshot taken while codemem is stopped, or use SQLite-safe backup tooling. Copying only the main database file while it is active in WAL mode can omit committed state. CODEMEM_RUNTIME_ROOT selects workspace config; it does not automatically move the database or key directory, so set CODEMEM_DB, CODEMEM_CONFIG, and CODEMEM_KEYS_DIR explicitly when restoring to new paths.

Before starting a restored peer, stop or isolate the old instance. Running two instances with the same private key clones one device identity. Then verify that the replacement reports the original device ID and fingerprint, refreshes coordinator presence, authenticates a signed peer request, and completes a direct sync. If the database is present but the private key is missing, invalid, or from another identity, codemem fails closed instead of silently rotating the key, unless the matching private key remains in the configured platform keychain.

The protected device.key file is the portable restore artifact even when CODEMEM_SYNC_KEY_STORE=keychain is enabled; codemem can repopulate the keychain from a matching restored file. If an operator deliberately removes that file and keeps the credential only in the platform keychain, it can authenticate only on that local platform; migrate the credential with platform-supported secure tooling before moving the peer. The database and public-key file alone are never sufficient.

If you use ephemeral storage, the peer can still be useful as a cache/backstop while it is running, but it must re-bootstrap after restart.

Granting scopes intentionally

Coordinator group enrollment is not enough. Grant the anchor peer to each Sharing domain explicitly:

codemem coordinator grant-scope-member team-alpha acme-work <anchor-device-id> --effect-id <effect-id> --db-path ~/.codemem/coordinator.sqlite
codemem coordinator grant-scope-member team-alpha oss-codemem <anchor-device-id> --effect-id <effect-id> --db-path ~/.codemem/coordinator.sqlite

Effect ids make membership mutations deterministic and idempotent; use a stable unique value for each intended mutation.

Review grants regularly:

codemem coordinator list-scope-members team-alpha acme-work --db-path ~/.codemem/coordinator.sqlite

Revoke a domain when the anchor peer should stop receiving future data for it:

codemem coordinator revoke-scope-member team-alpha acme-work <anchor-device-id> --effect-id <effect-id> --db-path ~/.codemem/coordinator.sqlite

Revocation is forward-looking. Rotate or destroy the anchor peer's local storage if you need to remove data already copied there.

What not to build around

  • Do not assume an anchor peer is authoritative for a Sharing domain.
  • Do not require a quorum of anchor peers for writes.
  • Do not route memory payloads through the coordinator.
  • Do not use project filters as a substitute for Sharing-domain grants.
  • Do not put personal and work data on the same anchor peer unless both domains are intentionally granted to that peer.

The mental model is Syncthing-shaped: durable always-on devices improve availability because they are online often, not because the protocol gives them special powers.