Peers

Peers is the compact pairing panel for linking this install to another askTheodor machine. Once two machines are paired they can mirror the same workspace, delegate tasks to each other, and (later) share Kafenio — all over a secure tunnel, with every request HMAC-signed using a key the two machines exchange at pairing.

This panel is the quick way to pair and prove the link. For the richer multi-machine control center — seeing every machine, pushing companies, watching remote runs — see the Fleet screen and the Teams overview.

This machine

A read-only card at the top shows this install’s identity:

• Name — this machine’s display name.
• Instance — its unique instance ID (shown shortened).
• Tunnel — the public URL peers reach you on, if your tunnel is running. If it shows not running, start it in Settings → Reception so other machines can connect to you.

Pair two machines

Pairing is mutual: one machine creates a code, the other accepts it, and both end up holding the same shared key.

1. Create a pairing code

On the machine others will connect to, pick the scopes to grant (see below), then 🔑 Create pairing code. Copy the generated code and carry it to the other machine.

The scopes you can grant:

• Sync — pull/push workspace rows (companies, workers, tasks, library) — mirror and clone.
• Delegate — run tasks on this machine on the peer’s behalf.
• Kafenio — read and post in this machine’s Kafenio rooms.
• API keys — receive your provider API keys (encrypted) so the peer can run using them.
• Full control — grants everything, current and future. Use only for machines you completely trust.

Grant the narrowest scopes that work

Each scope is a real permission you hand the other machine. Start with Sync only; add Delegate or API keys when you actually need them. Full control hands over the keys to the kingdom — reserve it for a machine you own and trust entirely.

2. Accept a pairing code

On the other machine, paste the code into the Accept box and click 🔗 Accept & pair. Both machines now share the signing key and appear in each other’s peer list.

Paired machines

Each paired machine is a row showing its name, short instance ID, granted scopes, and when it was last reached. Per row you get:

• 📡 Ping — send an HMAC-signed ping to confirm the secure link is live and the machine is reachable.
• Auto (sync scope) — keep this machine continuously mirrored. When on, the background scheduler syncs roughly every 90 seconds.
• 🔄 Sync (sync scope) — sync now: pull and push workspace changes (companies, workers, tasks, library) once. The result reports how many changes were pulled and pushed.
• 🛰 Delegate (delegate scope) — open a composer, describe a task, and Run on remote; the remote machine runs it autonomously and replies back.
• 🗑 — unpair the machine.

A status line at the bottom shows the result of your last action (paired, synced, pinged, delegated, or an error).

A tunnel is required to be reached

Other machines can only connect to you while your tunnel is running. Pinging and delegating to a peer needs that peer’s tunnel up; being mirrored or delegated from a peer needs yours. Start tunnels in Settings → Reception.

Pairing vs the Fleet screen

Use this panel for the one-time pairing and a quick ping or sync. For day-to-day multi-machine work — cloning a company onto another machine, pushing API keys, running a Plan on a remote, and seeing everything at a glance — head to the Fleet screen. The bigger picture lives in the Teams overview.

In practice

When pairing fails, check reachability first. Almost every failed pairing is one machine unable to see the other, not a bad code or a scope problem. Confirm the relevant tunnel is up before touching anything else — a pairing code is short-lived, so a slow debugging session can also expire it.

Grant the narrowest scope that makes the job possible. sync for a machine that should only mirror data, delegate when it should also run work you send it, full only for hardware you own outright. Widening later is a one-line change; discovering a peer could do more than you intended is not.

Direction matters. Delegating to a peer needs that peer reachable; being mirrored or delegated from one needs you reachable. If one direction works and the other doesn’t, that asymmetry is the answer.

Unpair machines you’ve retired. A stale peer entry is a credential that still exists for a box you may no longer control — worth a periodic look at the list, the same way you’d review who still has a key to the office.

🎓 Learn it hands-on: Fleet: a Team-Hub on a VPS

Terms in this page

• Peer — another askTheodor install you’ve paired with this one.
• Pairing — the mutual setup where one machine creates a code and the other accepts it, after which both share a signing key.
• Pairing code — the one-time string you copy from one machine and paste into the other to establish the link.
• Scope — a specific permission granted to a peer: sync, delegate, kafenio, API keys, or full control.
• Sync / mirror — keeping the same workspace rows (companies, workers, tasks, library) copied between two machines.
• Delegate — handing a task to another machine, which runs it autonomously and replies.
• Kafenio — askTheodor’s shared staff room; the kafenio scope lets a peer read and post in it.
• Instance ID — the unique identifier for one askTheodor install, used to tell machines apart.
• Tunnel — a public web address that lets other machines reach this one over the internet; started in Settings → Reception.
• HMAC signing — a cryptographic stamp added to every request between paired machines using their shared key, so each side can prove the message is genuine and untampered — safe even over a public tunnel.
• Auto-sync — a background loop that mirrors a paired machine automatically about every 90 seconds.
• Fleet — the broader multi-machine feature set (and its own screen) for managing several paired installs together.