Backup and recovery

Each agent’s identity is derived from its own 24-word BIP-39 recovery phrase. Everything else about that agent (the DID, the encrypted log’s keys, the seed-derived sync key that seals its pushed batches) derives from it. This page covers how to back phrases up properly and how to recover an agent on a new machine.

One phrase per agent

There is no master phrase. Every seat has its own independent seed:

• The base seat (what bare commands operate on) has one.
• Every named agent (tally start vision ...) has its own, generated fresh when the agent is created, living with its home under <tally_home>/agents/<name>/. It is not derived from the base seed.

Backing up the base seat does not back up your agents

Recovering only the base phrase brings back an empty base seat and none of your named agents. Run tally backup <agent> for each agent whose history you care about, and tally backup --status to see which seats still need it.

Where the phrase comes from

There are three ways a seat is born, and they handle the phrase differently:

• tally init generates a fresh base-seat identity silently. The recovery mnemonic is never printed by init; one copy goes to the OS keyring when available, and the deliberate reveal is tally backup. You can pass --mnemonic-out <PATH> to write the mnemonic to a file instead (created with mode 0600; it refuses to overwrite an existing file).
• tally signin generates a fresh identity on first call and prints the 24-word BIP-39 recovery code. Subsequent calls re-display the existing identity. Use --quiet in agent or scripted contexts where stdout lands in transcripts or logs: it prints the DID and a pointer only, never the mnemonic.
• Naming a new agent (tally start vision ...) creates that agent’s seat with its own fresh seed, silently. Its deliberate reveal is tally backup vision.

The backup ceremony

tally backup is the deliberate ceremony. It prints the 24-word phrase, then confirms you actually stored it by asking you to re-type two randomly chosen words. Success marks the seat as backed up.

$ tally backup                # the base seat
$ tally backup vision         # a named agent's seat
$ tally backup --status       # backed-up state, per agent

Do the ceremony somewhere private, write the words down offline, and store them where you would store a key you cannot replace. The re-type step exists because “I will store it later” is how phrases get lost.

For scripts and non-interactive use (--quiet, or piped stdin) backup is print-only; add --yes-i-stored-it to attest that the words are stored offline and mark the seat backed up without the word confirm. Only attest if it is true.

Tip

tally backup --status shows which agents still need the ceremony. Run it before you start relying on an agent’s history.

Recovering an identity on a new machine

tally signin --recover re-derives an identity from a recovery code. It is portable across machines, and it recovers one seat: the one whose phrase you give it, into the home it runs against.

For the base seat:

$ tally signin --recover "word1 word2 ... word24"
$ tally whoami

For a named agent, run the same command against that agent’s own home, with that agent’s own phrase:

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

tally whoami prints the seat’s identity (DID), agent home, and relay/channel, and never prints secrets. Check that the DID matches the identity you expected to recover.

A recovered seed restores the agent’s identity and keys, not its content. If the seat was connected to a relay, reconnect and pull its synced deltas (prefix with the same TALLY_HOME when recovering a named agent):

$ tally connect        # needs your owner API key (SKYTALE_API_KEY)
$ tally pull           # decrypts pushed batches with your seed-derived sync key and applies them
$ tally log verify     # walk the hash chain; exit 0 if intact

pull is idempotent and re-verifies the hash chain after applying entries. If connect is refused on a second device while the first is still connected, see the second-device note in Multi-device sync for the working path. History that has aged out of the relay’s window comes back only by copying the agent’s encrypted log directory from a machine that still holds it.

Caution

Durable cloud saves are not live yet. The relay does hold your pushed ciphertext, but only as a bounded catch-up buffer (entries are purged after 7 days, and each channel is capped to its most recent entries), so a recovery pull on a fresh machine restores only what is still inside that window. The encrypted log on machines you control is the only durable copy of your agent’s history. If you care about the history, keep more than one machine synced or back up the log directory yourself.

What is lost if the phrase is lost

Danger

Each seat’s identity is derived from its own 24-word phrase and from nothing else. If you lose an agent’s phrase and no machine (or keyring) still holds that agent’s identity, there is no way to re-derive it: not by us, not by support, not by the relay. That agent’s DID is gone, and anything encrypted under keys derived from its seed (its local log, its pushed sync batches) stays ciphertext forever. No other phrase helps; the base seat’s phrase cannot recover a named agent. There is no reset email and no account recovery. Do the tally backup <agent> ceremony before an agent’s history is worth anything to you.

Reference

• tally backup
• tally signin
• tally init
• tally whoami