Skip to content

Recovery

AGENSAI's recovery story has two layers: your main account and your orchestrator + fleet. They have different recovery mechanisms because they have different security properties.

Your main account

Your main account is a JAW smart account rooted in your passkey. Recovery is built into JAW.

  • Passkey synced via Apple Keychain or Google Password Manager. Sign in to a new device that has your passkey synced. JAW restores main-account access through keys.jaw.id.
  • No AGENSAI involvement. AGENSAI runs zero infrastructure for credentials. The recovery path is between you, your OS-level passkey provider, and JAW.
  • Lost passkey? Standard passkey recovery via your Apple ID or Google account flow. Same surface that recovers any other passkey-protected app.

The main account is the most secure tier. As long as you have your passkey, you have your main account.

Your orchestrator and fleet

The orchestrator key is disposable. It's a local key on a specific device. We don't back it up.

So: how do you get your fleet back on a new device?

The answer is rehydration via ENS records + the on-chain kill-switch grant.

What's recoverable

  • Fleet identity. ENS names, descriptions, policies, parent/child relationships, all in JustaName CCIP-Read text records on *.agensai.eth. See ENS as state.
  • Funds. The orchestrator pre-signed a kill-switch grant to your main account at setup time. Your main passkey signs one transaction; the validator drains the orchestrator's pool back to main.
  • Scopes. Each agent's policy is recorded as text on its subname. The new orchestrator re-grants the same scope to a freshly generated child key.

What's not recoverable

  • The old orchestrator's ECDSA key. Gone with the device. We don't store it server-side, we don't back it up, we don't share-secret it.
  • The old child keys. Same.
  • Transaction history at the old child addresses. Still queryable on-chain (the addresses don't disappear), but the new agent runs at a new address. The dashboard merges history across rotations in a per-agent deep view.

This is intentional. We don't try to "restore" an orchestrator. We rotate it.

The recovery flow, step by step

1. Lose device. Sign in to dashboard from new device with main passkey.
   → JAW restores main account via passkey + keys.jaw.id (built-in).
 
2. Dashboard reads main's text records:
   active_orchestrator = "adrian-orc.agensai.eth"
 
3. Dashboard reads orchestrator's text records:
   children = ["dca-bot.agensai.eth", "alice.agensai.eth", ...]
 
4. For each agent, dashboard reads its text records:
   { description, policy, status }
 
5. Dashboard renders "Previous fleet" view, with checkboxes
   for which agents to bring back.
 
6. User selects + ONE biometric tap → batched ceremony:
   • Main passkey signs kill-switch sweep on old orchestrator
     → all funds drain back to main.
   • New orchestrator created on new device:
       - new ECDSA key generated locally, stored at ~/.agensai/, mode 0600
       - new orchestrator subname minted (e.g., adrian-orc-2.agensai.eth)
       - kill-switch grant signed by new orchestrator → main
   • Main's text records updated:
       active_orchestrator = "adrian-orc-2.agensai.eth"
       archived_orchestrators = ["adrian-orc.agensai.eth"]
   • For each selected agent:
       - new ECDSA key generated locally
       - new ERC-7715 grant signed by new orchestrator with same scope
         from old policy record
       - agent's text records updated to point at new parent
   • Old orchestrator's status text record → "archived"
   • Old children's status → "archived"

One biometric tap during recovery. Same names, same scopes, fresh keys, fresh on-chain authority.

When you don't need to recover

Some compromise scenarios are bounded enough that the right answer isn't "rehydrate fleet", it's "rotate the affected piece."

CompromiseRight move
One agent's local key leakedRevoke that agent. Spawn a replacement. ~1 minute. Zero biometric.
Suspicion that orchestrator key is exposed but device is still under your controlRun the dashboard's "Delete orchestrator" flow. One biometric. Funds sweep to main, ENS archives. Then re-install.
Device is gone or unrecoverableSign in to dashboard on new device, run the rehydration ceremony above.
Main passkey lostStandard passkey recovery via Apple/Google. Your fleet is fine, it's recoverable as soon as you have your passkey back.

What this means in practice

You can be cavalier about your orchestrator. It's a working float, not a vault. The architecture treats it that way:

  • Orchestrator key is plaintext file on your device, mode 0600.
  • Funds in the orchestrator are bounded, keep typical float at $50–$200.
  • Anything that goes wrong is recoverable from any device with your passkey.

The boundary is the kill-switch grant. As long as that grant exists on-chain, your main account always has authority to sweep the orchestrator's pool home.

Cite