Multi-device sync

Goal: the agent you use on device A, resumable on device B with the same identity and the same history. What travels is sealed log deltas the relay cannot read; that side of the story is covered in What syncs, and what the cloud can see and is not repeated here.

The one thing to internalize before any recipe: sync and recovery are per agent, not per install. Every named agent (tally start vision ...) is its own seat, with its own independent seed, its own 24-word phrase, and its own home under <tally_home>/agents/<name>/. The base seat (what bare commands operate on) is a separate seat with a separate seed. See The agent and its home.

Back up each agent, not just the base seat

If you only back up your base seed, your named agents are NOT recoverable. Their seeds are not derived from the base seed, so recovering the base phrase alone brings back an empty base seat and none of your agents. Run tally backup <agent> for each agent whose history you care about; tally backup --status shows which agents still need the ceremony.

The bare tally connect, tally push, tally pull, and tally signin --recover commands operate on the base seat only; they do not take an agent name today (only tally backup <agent> does). The per-agent path is to point TALLY_HOME at the agent’s own home, which the recipes below do. Agent-name arguments on the sync verbs are a planned follow-up; the TALLY_HOME form will keep working either way.

Before you start

• Pick the agent you are syncing. The examples use a named agent vision, whose home is ~/.tally-coding-cli/agents/vision (adjust if you set TALLY_HOME).
• Back up that agent’s phrase on device A if you have not: tally backup vision prints its 24-word recovery phrase and confirms you stored it. Device B needs those words.
• Device A needs the owner API key in $SKYTALE_API_KEY (or passed as --api-key to connect) for the one-time connect.

Device A: connect the agent’s home, then push

Provision the agent’s seat onto its relay channel, once. Nothing connects a named agent automatically, so this step is yours to run:

$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally connect

connect registers the channel, runs the device-grant, and stores a channel-scoped credential to that home’s relay.json. The channel defaults to the seat’s own pronoic/agents/<hex>, derived from the seat identity, so each agent syncs on its own channel.

Then publish everything appended so far:

$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally push

push batches every log entry since the last push, seals the batch with that agent’s seed-derived sync key, and publishes the ciphertext.

Once the agent’s home is connected, the launch verbs (tally continue vision, tally start vision, tally run vision) sync it automatically on launch, so the manual push is mostly a first-time and finish-line tool.

Device B: recover the agent, connect, pull

Re-derive the agent’s identity from its own recovery phrase, into the same agent home path:

$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally signin --recover "<vision's 24-word mnemonic>"

Same seed, same DID, same seat; vision is now a real named agent on device B (agent homes are resolved by directory, so the launch verbs and tally agent list see it).

Because the seat’s default channel is derived from that identity, connecting on device B lands on the same channel device A publishes to:

$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally connect
$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally pull

Second-device connect, honestly

The device-grant API accepts one active grant per identity today, so connect for an already-connected agent can be refused on a second device with a conflict error. A fix that lets a second device connect cleanly is in flight. Until it lands, the working path is to copy the agent’s relay credential from device A instead of running connect on device B: copy agents/vision/relay.json from device A into the same path on device B (it is a channel-scoped credential; transfer it privately and keep its permissions owner-only). With the credential in place, pull works. If connect succeeds on your second device, the fix has landed and no copy is needed. Ignore any error text suggesting a SKYTALE_SEAT variable; it does not exist.

pull back-fills the channel, decrypts each batch locally with the same seed-derived key, and applies the entries to the local log. Cursors, in one sentence: each device saves how far into the channel it has read, so a pull fetches only what it has not applied yet. Idempotency, in one sentence: applying entries is idempotent and the hash chain is re-verified after apply, so re-pulling the same batches changes nothing.

Remember what the phrase alone buys: a seed restores the agent’s identity and keys, not its content. The history arrives via pull (bounded by the relay’s retention window, below) or by copying the agent’s encrypted log directory from a machine that still holds it.

The base seat

The same recipe with the TALLY_HOME= prefix dropped syncs the base seat: tally backup, tally connect, tally push on device A; tally signin --recover, then the credential step, then tally pull on device B. Syncing the base seat does nothing for your named agents; each one is its own seat and needs its own pass.

Check it worked

# same DID on both devices; prints no secrets
$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally whoami

# event count and chain verification on device B should match device A after a pull
$ TALLY_HOME=~/.tally-coding-cli/agents/vision tally status

Day to day

Push on the device you finished working on; pull on the device you are about to work on. If you use the launch verbs, tally continue, tally start, and tally run include a sync step by default (--no-sync skips it) for the agent they launch, provided that agent’s home has been connected, so a launch on device B picks up device A’s latest context without a manual pull.

One retention fact to plan around: the relay’s archive is a bounded catch-up buffer (entries are purged after 7 days, and each channel is capped to its most recent entries), not a durable store. A device that stays offline past that window can miss batches that have aged out; keep your regularly used machines pulling regularly, and see Backup and recovery for what counts as a durable copy.

Troubleshooting

tally doctor diagnoses the local setup: identity, home, harness installs, relay and API reachability, and clock skew, with a pass, warn, or fail per check and an actionable fix. It exits non-zero if anything fails, so it also works as a preflight in scripts. Run it with the same TALLY_HOME as the agent you are debugging. If push or pull complains about a missing relay, connect has not been run for that home (or the TALLY_RELAY_URL / TALLY_RELAY_JWT variables are unset); the error output says which.

Where next

• The agent and its home : base seat vs named agents, and what lives in a seat home
• What syncs, and what the cloud can see : exactly what leaves the machine, and in what form
• Backup and recovery : per-agent seed custody, the ceremony, and what loss means
• tally connect : every connect flag, including custom relay and API URLs