Recover a lost key¶

Read this before you lose a key, not after

In an encrypted VCS, losing your identity key is a data-loss event. Re-cloning does not help — TOVIO content is encrypted to your key, so without it every protected file you could read stays opaque ciphertext forever. The recovery phrase is the one thing that prevents this, and at a terminal tovio init shows it to you exactly once. Put it somewhere safe today, while you still can.

What is, and is not, at risk¶

If you have lost your identity key, take a breath. Here is the honest picture:

Safe regardless: your commits, lane history, and every clear (unencrypted) file. These are not encrypted to you and re-clone fine. Your work is not gone.
Recoverable — if you have your recovery phrase: the protected content at HEAD that you are still authorized to read. tovio key recover rebuilds your access from the phrase.
Not recoverable: protected content whose key was rotated away while you were locked out (for example, a path you were revoked from in the meantime), and — the hard one — anything at all, if you lost both your identity key and your recovery phrase. That combination is unrecoverable by design; no server holds a copy.

So the question that decides your outcome is simply: do you have your recovery phrase?

What the recovery phrase is¶

When an identity is created — at tovio init --mode team/agentic, or at tovio identity init on an existing Simple repo — TOVIO generates an independent recovery keypair. The phrase is 64 hex characters, and the recovery public key is added as an extra recipient on your wrapped key material, which is what lets it re-derive your access later. It lives only outside the synced object store, so it never travels with the repository.

How you receive it depends on whether you are at a terminal, and the difference matters:

At an interactive terminal, the phrase is printed once, in a box, and you are asked to acknowledge it:

  ┌─ RECOVERY KEY — save this before your first protected commit ─────────────
  │  Recovery phrase:  a1b2c3…
  │
  │  WARNING: if you lose BOTH your identity key AND this recovery phrase, your
  │  protected files are UNRECOVERABLE. TOVIO does not keep a copy.
  └──────────────────────────────────────────────────────────────────────────
  Type `saved` once you have escrowed the phrase (or press Enter to skip):

Copy it out before you answer. On tovio init there is no file to fall back on — if you scroll past this box, the phrase is gone. (tovio identity init is slightly kinder: it keeps an owner-only fallback file until you type saved, and typing saved is what removes it. Skipping the prompt there leaves the file behind, and the command tells you where.)

Unattended — under --json, --quiet, or with no TTY, as in CI or a script — there is nothing to prompt, so the phrase is written to .tovio/tovio-recovery-key.txt instead, owner-only and kept out of every commit:

  Recovery phrase written to …/.tovio/tovio-recovery-key.txt (owner-only, kept out of commits) — move it somewhere
  safe (a password manager), then delete it. Losing BOTH your key and this phrase is unrecoverable.

Either way, get the phrase somewhere safe before your first protected commit, and leave no copy beside the identity it protects — a single lost machine taking both is the exact failure the phrase exists to prevent.

Nothing but your escrow can let you back in

You are the only one holding the recovery phrase. There is no server or administrator who can let you back in, and TOVIO warns you of this at setup for a reason: losing both the identity key and the phrase is final. A Key-Authority- or HSM-held escrow that lets an administrator re-provision a locked-out or departed developer without their cooperation is a v2 enterprise profile, not something a Team repository can do today.

Confirm your phrase is safe¶

There is no command that reports escrow status — tovio key status lists attribute certificates, not recovery state. Confirming it is a manual check, so do it now rather than in a crisis:

You can find the phrase where you put it (password manager, printed copy).
No copy of it is left in the repository. In particular, if you set the repo up unattended, check that .tovio/tovio-recovery-key.txt is gone. The absence of that file is not by itself proof of escrow — an interactive tovio init never creates one.

Recover access with `tovio key recover`¶

When you have lost your identity key but still hold your recovery phrase, restore access. --from takes a file holding the phrase, so put it back on disk first:

$ tovio key recover --from ./recovery-phrase.txt
✓ Recovered — installed a fresh identity did:key:…
  Re-sealed 3 protected file(s) at HEAD to the recovered owner — YOU can read them again.
  Audit chain reset: pre-recovery entries were signed by the lost key and cannot be verified,
  so a fresh audit segment starts from this recovery (the old entries are kept but orphaned).

  Your OLD identity key remains lost; this new key is now your identity. Back it up with
  `tovio key export`, and keep your recovery phrase safe for the future.

What this does:

Generates a fresh identity keypair for you (this is also an identity key rotation — your old, lost key is retired). This is not tovio key import, which restores the same key from a passphrase backup; use recover only when the identity key itself is gone.
Re-seals the protected content at HEAD to the new keypair. It cannot recover content whose keys were rotated away while your key was lost — that ciphertext is no longer encrypted to any key you can obtain.
Resets your audit chain. Entries written before the recovery were signed by the lost key and can no longer be verified, so the recovery starts a fresh segment. The old entries are kept, but orphaned.

Recovery can drop teammates and devices

Teammate and device recipients whose access claims were signed by your lost key no longer verify, so protected content is not re-sealed to them. key recover lists every DID it dropped. After a recovery, re-grant those teammates with tovio access grant --identity <file> and re-approve devices with tovio device approve …; they regain access on the next commit.

After recovery, back the new key up with tovio key export and keep your recovery phrase somewhere safe for next time.

Recommended setup checklist¶

When the identity is created, capture the recovery phrase immediately — before the first protected commit. At a terminal that means copying it out of the box before you answer the prompt; unattended it means moving .tovio/tovio-recovery-key.txt and then deleting it.
Store it separately from your identity key: a password manager, or a printed phrase kept offline.
Back the identity's root device key up too, with tovio key export … --passphrase-file …: that restores the same key after a keychain loss, which is a far cheaper outcome than a recovery.
Periodically confirm you can still find the phrase. No command reports this for you.

Next steps¶

Manage your keys — routine key health, rotation, enrolling a second device, and backing up the root key.
Security — the full list of what v1 protects and the accepted residual risks.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure