# Deploying the coordinator The built-in TypeScript coordinator is the canonical **operator deployment** target for cross-network discovery. Normal teammate sharing is **Projects → Sharing → Devices → Health**; the coordinator, Teams, Spaces, grants, and direct-peer state are Advanced compatibility and operations mechanics. The coordinator HTTP service is Hono-based, but the canonical deployment path today is still the built-in `codemem coordinator serve` runtime on Node/Linux with a local SQLite database. If your end goal is Cloudflare, validate this Linux/Node flow first, then use the dedicated Worker runbook in [Cloudflare coordinator deployment](cloudflare-coordinator-deployment.md). If you want the fastest clean validation path, use [the coordinator E2E runbook](coordinator-e2e-runbook.md) alongside this guide. ## What the coordinator does (and does not do) - It enrolls devices in a coordinator group and advertises fresh peer addresses. - It does **not** grant a Project, create a direct peer relationship, or relay memory payloads. - **Sharing** manages Project recipients, while authoritative Team policy determines which member devices are eligible. **Devices** shows registered devices and direct Project access without inferring Team access from membership; **Health** distinguishes waiting from needs-attention recovery. - Removing Project access stops future delivery but cannot erase a copy already delivered to a device. Use the controls below only when you operate a coordinator, diagnose compatibility, or maintain an existing integration. Internal identifiers, fingerprints, addresses, scopes/grants, filters, epochs, and cursors belong in this operator surface—not the normal sharing workflow. ## Quick start (native) ```fish # Install codemem CLI (makes the `codemem` command available) npm install -g codemem # Create a coordinator group codemem coordinator group create my-team --db-path ~/.codemem/coordinator.sqlite # Set an admin secret (required for creating invites via the API) set -x CODEMEM_SYNC_COORDINATOR_ADMIN_SECRET (openssl rand -base64 32) # Start the coordinator codemem coordinator serve --db-path ~/.codemem/coordinator.sqlite --coordinator-host 0.0.0.0 --coordinator-port 7347 ``` The coordinator is now listening on port 7347. Devices on the same network can connect using this machine's IP address. **Important:** Save the admin secret — you'll need it in your client config to create invites from the UI or API. The coordinator rejects admin operations (invite creation, join request review) without it. ## CLI reference ### Coordinator server ```fish codemem coordinator serve [OPTIONS] ``` | Option | Default | Description | |-------------|---------------|----------------------------------------| | `--db-path` | `~/.codemem/coordinator.sqlite` | Path to coordinator SQLite database | | `--coordinator-host` | `127.0.0.1` | Bind address (`0.0.0.0` for all interfaces) | | `--coordinator-port` | `7347` | Listen port | ### Team management (Advanced/operator) ```fish # Create a group codemem coordinator group create --db-path # List groups codemem coordinator group list --db-path # Enroll a device directly (admin) codemem coordinator device enroll \ --fingerprint --public-key-file --db-path # List enrolled devices codemem coordinator device list --db-path # Rename, disable, or remove a device codemem coordinator device rename --name "work-laptop" --db-path codemem coordinator device disable --db-path codemem coordinator device remove --db-path # Invite / join-request commands codemem coordinator invitation create --db-path codemem coordinator request list --db-path codemem coordinator request approve --db-path codemem coordinator request deny --db-path ``` ### Invite and join flow ```fish # Create an invite (admin) codemem coordinator invitation create --db-path # Import an invite (teammate) codemem coordinator invitation accept # List pending join requests (admin) codemem coordinator request list --db-path # Approve or deny (admin) codemem coordinator request approve --db-path codemem coordinator request deny --db-path ``` ## Container deployment No official Dockerfile is shipped yet. Here is a minimal example: ```dockerfile FROM node:24-slim RUN npm install -g codemem VOLUME /data EXPOSE 7347 ENTRYPOINT ["codemem", "coordinator", "serve", \ "--db-path", "/data/coordinator.sqlite", \ "--coordinator-host", "0.0.0.0", "--coordinator-port", "7347"] ``` Build and run: ```fish docker build -t codemem-coordinator . docker run -d --name coordinator -p 7347:7347 -v coordinator-data:/data codemem-coordinator ``` Initialize the group from the host: ```fish docker exec coordinator codemem coordinator group create my-team --db-path /data/coordinator.sqlite ``` ## Exposing the coordinator If your teammates are not on the same LAN, you need to make the coordinator reachable. Two recommended options: ### Tailscale Funnel Tailscale Funnel exposes a local port to the internet via your Tailscale network with automatic TLS. ```fish # Start the coordinator codemem coordinator serve --db-path ~/.codemem/coordinator.sqlite --coordinator-host 0.0.0.0 --coordinator-port 7347 # In another terminal, expose via Funnel tailscale funnel 7347 ``` Teammates configure their client with the Funnel URL (e.g. `https://your-machine.ts.net:443`). ### Cloudflare Tunnel Cloudflare Tunnel exposes a local port through Cloudflare's network, giving you a stable public hostname with TLS. This is the simplest way to put the built-in TS coordinator behind Cloudflare without changing the coordinator runtime itself. ```fish # Start the coordinator codemem coordinator serve --db-path ~/.codemem/coordinator.sqlite --coordinator-host 127.0.0.1 --coordinator-port 7347 # Start the tunnel cloudflared tunnel --url http://localhost:7347 ``` Use the generated `*.trycloudflare.com` URL for quick testing, or configure a named tunnel with a custom domain for production use. ## Client configuration (Advanced/operator) Once the coordinator is reachable, teammates configure their codemem client: **Admin's machine** (the device running the coordinator): ```json { "sync_enabled": true, "sync_coordinator_url": "https://coord.example.com", "sync_coordinator_group": "my-team", "sync_coordinator_admin_secret": "" } ``` The admin secret lets you create invites and review join requests from the viewer UI or API. Only the admin needs this. **Teammate devices:** ```json { "sync_enabled": true, "sync_coordinator_url": "https://coord.example.com", "sync_coordinator_group": "my-team" } ``` Or via environment variables: ```fish set -x CODEMEM_SYNC_COORDINATOR_URL "https://coord.example.com" set -x CODEMEM_SYNC_COORDINATOR_GROUP "my-team" ``` Or through the viewer UI: Settings → Device Sync → Coordinator URL / Group. **Note:** Teammates who join via an invite link don't need to configure anything manually — the invite import auto-configures `sync_coordinator_url` and `sync_coordinator_group`. Joining the coordinator Team enrolls the device for coordinator-backed discovery, but it does not automatically create a local `sync_peers` relationship or Project grant. Direct sync still depends on explicit `sync_peers` state. ## Onboarding teammates (Advanced/operator) ### Admin-driven enrollment The admin can enroll a teammate's device directly from the local coordinator machine: ```fish codemem coordinator device enroll my-team \ --fingerprint --public-key-file \ --db-path ~/.codemem/coordinator.sqlite ``` ### Invite-driven enrollment (recommended) The admin creates an invite and shares it: ```fish codemem coordinator invitation create my-team --db-path ~/.codemem/coordinator.sqlite ``` This outputs an encoded invite string. Share it with the teammate, who imports it: ```fish codemem coordinator invitation accept ``` Or paste the invite in the viewer UI under **Advanced → Team sync → Join team**. For an exact-Project invitation, use `--recipient-name "Your name"` or `--device-name "Your device"` to replace legacy configured names that look like internal identifiers. Team-member and add-device recipient invitations must be accepted in the viewer because codemem must show and confirm their reviewed access details before joining. If the invite policy is `approval_required`, the teammate's join request will appear in the admin's pending queue. The admin approves it from the CLI or the viewer UI. ## Data model (operator terms) The coordinator stores: - group definitions - enrolled device records (device ID, public key, fingerprint, display name, status) - presence records (device addresses, TTL-based expiry) - invite tokens (group-scoped, policy, expiry) - join requests (pending, approved, denied) All data lives in a single SQLite database. The coordinator does **not** store or relay memory payloads — direct peer-to-peer sync remains the data path. ## Troubleshooting **Coordinator not reachable**: verify the `--coordinator-host` binding. Use `0.0.0.0` to listen on all interfaces. Check firewall rules and that the tunnel/funnel is active. **Device not enrolled**: run `codemem coordinator device list --db-path ` to confirm enrollment. Use the invite flow for self-service enrollment. **Presence not refreshing**: check that the client's `sync_coordinator_url` matches the coordinator's reachable address and that `sync_coordinator_group` matches a group the device is enrolled in.