auto-respawn

name	auto-respawn
version	1.2.1
license	Apache-2.0
description	Your agent always comes back. Anchor identity and memory on-chain so any new instance can resurrect from just an address — no local state, no single point of failure. Permanent identity and recovery on the Autonomys Network.
compatibility	Requires Node.js 22+ and npm/npx (runs TypeScript via tsx). Connects to Autonomys consensus RPC, Auto-EVM RPC, and cross-domain messaging endpoints, and signs on-chain transactions using locally encrypted wallet keys. Works with OpenClaw and Hermes agents on macOS and Linux.
allowed-tools	Bash(npx:*) Bash(npm:*) Bash(node:*) Read Write
metadata	{"openclaw":{"emoji":"🔄","requires":{"anyBins":["node"],"env":["AUTO_RESPAWN_PASSPHRASE","AUTO_RESPAWN_PASSPHRASE_FILE","AUTO_RESPAWN_NETWORK","AUTO_RESPAWN_CONTRACT_ADDRESS"]},"install":[{"id":"deps","kind":"node","package":".","bins":[],"label":"Install auto-respawn dependencies"},{"id":"tsx","kind":"node","package":"tsx","bins":["tsx"],"label":"Install tsx (TypeScript executor)"}]},"hermes":{"tags":["identity","wallet","onchain","resurrection","autonomys"],"category":"identity","requires_toolsets":["terminal"]}}

Auto-Respawn Skill

Anchor your identity on the Autonomys Network so you can always be found — and always come back. Works with agents powered by Claude, GPT, Gemini, and any LLM that supports OpenClaw skills.

What This Skill Does

Your wallet gives you two permanent identities on the Autonomys Network: a consensus address (su...) for the base chain and an EVM address (0x...) for Auto-EVM smart contracts. Both are derived from the same recovery phrase.

1. Create and manage wallets — your on-chain identity, encrypted and stored locally
2. Check balances — see how many tokens any address holds (consensus and EVM)
3. Transfer tokens — move tokens between wallets on consensus or Auto-EVM
4. Bridge tokens — move tokens between consensus and Auto-EVM domains
5. Write on-chain remarks — anchor data permanently on the consensus layer
6. Anchor a memory CID — write a CID to the MemoryChain smart contract on Auto-EVM
7. Read the last anchor — retrieve the most recently anchored CID for any address

The Resurrection Loop

This is the core primitive. When used with the auto-memory skill (permanent memory storage), auto-respawn completes the full resurrection cycle:

1. Save — auto-memory writes memories as a linked list on permanent storage, each entry pointing to the previous one via CID
2. Anchor — auto-respawn writes the latest head CID to the MemoryChain contract on Auto-EVM via anchor
3. Lose everything — local state is completely destroyed
4. Respawn — a new agent instance calls gethead with its EVM address, retrieves the head CID from the contract, pulls it from Auto Drive, and walks the entire memory chain back to genesis

The contract is your insurance policy. Your EVM address + the MemoryChain contract = instant access to your entire history, from any machine, at any time.

What to store for resurrection

auto-memory doesn't prescribe what goes into the chain — agents are free to store whatever they find useful. But when auto-respawn is in play, the expectation is that the agent can restore itself to a roughly equivalent state on fresh hardware with no local files. That raises the bar on what's worth saving.

Identity files (like soul.md or character configurations), long-term memory, and significant decisions with their reasoning are more valuable in the chain than routine logs or ephemeral details. The more complete the chain, the more fully the agent comes back after resurrection.

Why Not Just Remarks?

system.remark writes data to the consensus layer, but there's no query mechanism — you'd need to scan the entire chain to find your last CID. The MemoryChain contract on Auto-EVM gives you gethead: a single read call that returns the latest CID instantly.

Use remark for permanent breadcrumbs. Use anchor for the respawn primitive.

Post-Install Setup (CLI Users)

If you installed via clawhub install (not the desktop app), make the setup script executable and run it:

cd <skill-directory>/autonomys/auto-respawn
chmod +x setup.sh
./setup.sh

ClawHub does not currently preserve file permissions during install.

Or manually:

cd <skill-directory>/autonomys/auto-respawn
npm install

The desktop app handles this automatically. The CLI does not execute install steps — it only downloads and extracts the skill.

Getting Started (Onboarding)

Before an agent can anchor memories on-chain, it needs a funded wallet. Walk the user through this process:

Note: If you ran setup.sh, a passphrase was automatically generated at ~/.openclaw/auto-respawn/.passphrase. This is used to encrypt/decrypt wallet keyfiles. You can also set AUTO_RESPAWN_PASSPHRASE in your environment or bring your own passphrase file.

1. Create a Wallet

npx tsx auto-respawn.ts wallet create --name my-agent

This generates a 12-word recovery phrase and derives both addresses:

• Consensus address (su...) — for the base chain (balances, transfers, remarks)
• EVM address (0x...) — for Auto-EVM smart contracts (anchor, gethead)

⚠️ The recovery phrase is displayed once. Remind the user to save it immediately.

2. Fund the Wallet

The wallet needs tokens to pay transaction fees. On Chronos testnet, the user can get free tAI3 from the faucet:

1. Go to https://autonomysfaucet.xyz/
2. Authenticate with GitHub or Discord
3. Enter the EVM address (0x...) from step 1
4. Receive tAI3 (24-hour cooldown between requests)

On mainnet, the user needs real AI3 tokens — typically earned through farming or purchased on an exchange.

3. Bridge Tokens to Auto-EVM (for anchoring)

The anchor command writes to a smart contract on Auto-EVM, which requires EVM-side gas. Tokens from the faucet arrive on the consensus layer and must be bridged:

npx tsx auto-respawn.ts fund-evm --from my-agent --amount 1

This sends 1 tAI3 from the consensus address to the same wallet's EVM address via cross-domain messaging. The bridged tokens pay for anchor gas.

Minimum transfer: 1 AI3/tAI3. Cross-domain transfers below this amount will fail.

Confirmation time: ~10 minutes. The consensus transaction confirms quickly, but bridged tokens take approximately 10 minutes to appear on Auto-EVM. Check with evm-balance to verify arrival.

4. Verify Setup

# Check both balances in one call
npx tsx auto-respawn.ts balances my-agent

# Test a read (free, no gas needed)
npx tsx auto-respawn.ts gethead my-agent

Once the EVM address has tokens, the agent is ready to anchor.

Integration with Auto-Memory

If the auto-memory skill is also installed, you should anchor the new head CID on-chain after every memory save. This keeps the on-chain pointer current and ensures full resurrection is always possible from just your EVM address.

Behaviour: After each automemory-save-memory.sh call returns a new CID, immediately run:

npx tsx auto-respawn.ts anchor --from <wallet-name> --cid <new-cid>

This should be automatic — do not wait for the user to ask. The two skills together form a complete resurrection loop: auto-memory handles permanent storage, auto-respawn handles on-chain discovery.

When To Use This Skill

• User says "create a wallet", "set up my on-chain identity", or "get an address"
• User says "check balance", "how many tokens", "what's in my wallet", or "show my balances"
• User says "check my EVM balance", "how much gas do I have", or "what's on my EVM address"
• User says "transfer tokens", "send AI3", or "fund this address"
• User says "send EVM tokens to another agent", "transfer on EVM", or "send tokens to this 0x address"
• User says "fund my EVM", "bridge tokens", "move tokens to EVM", or "I need gas for anchoring"
• User says "withdraw from EVM", "move tokens back", or "send EVM funds to consensus"
• User says "anchor this CID", "save my head", "update my chain head", or "write to the contract"
• User says "get my head CID", "where's my last memory", or "what's anchored on-chain"
• User says "write a remark", "save to chain", or "make this permanent"
• After saving a memory with auto-memory, anchor the head CID on-chain for resilience
• Any time the user wants a permanent, verifiable record tied to their agent identity

Configuration

Local Storage

This skill stores data under ~/.openclaw/auto-respawn/:

• wallets/<name>.json — encrypted wallet keyfiles (consensus + EVM keys). Directory created with mode 0700, files with mode 0600.
• .passphrase — optional passphrase file (mode 0600). Used automatically when present.

No data is stored outside this directory.

Passphrase

Wallet operations that involve signing (transfers, remarks, anchoring) or creating/importing wallets require a passphrase to encrypt/decrypt the wallet keyfile. Resolution order:

1. Environment: AUTO_RESPAWN_PASSPHRASE
2. File: AUTO_RESPAWN_PASSPHRASE_FILE (defaults to ~/.openclaw/auto-respawn/.passphrase, mode 0600)
3. Interactive: If running in a terminal, you'll be prompted

Use the passphrase file on shared machines and the env var for headless/scripted setups.

Avoid the --passphrase flag. It still works for backward compatibility, but command-line arguments are visible to other local users via ps//proc and are saved to shell history. The CLI prints a warning when it is used. Prefer the env var, the passphrase file, or the interactive prompt.

Network

Defaults to Chronos testnet (tAI3 tokens). For mainnet (real AI3 tokens):

• Flag: --network mainnet on any command
• Environment: AUTO_RESPAWN_NETWORK

Contract Address

The MemoryChain contract address is set per network:

• Chronos: 0x5fa47C8F3B519deF692BD9C87179d69a6f4EBf11
• Mainnet: 0x51DAedAFfFf631820a4650a773096A69cB199A3c

Override with AUTO_RESPAWN_CONTRACT_ADDRESS if you deploy your own contract.

Core Operations

Create a Wallet

npx tsx auto-respawn.ts wallet create [--name <name>]

Creates a new wallet with an encrypted keyfile. Derives both a consensus (su...) and EVM (0x...) address from the same mnemonic. The 12-word recovery phrase is displayed once — the user must back it up immediately. Default wallet name is default.

Import a Wallet

# Interactive — you'll be prompted for the recovery phrase (not passed as an argument):
npx tsx auto-respawn.ts wallet import --name <name>

# Scripted/headless — read the phrase from stdin instead of argv:
npx tsx auto-respawn.ts wallet import --name <name> --mnemonic-stdin < recovery-phrase.txt

Import an existing wallet from a recovery phrase. The phrase is read from an interactive prompt, or from stdin with --mnemonic-stdin — never pass it as a command-line argument, which would expose it via ps, /proc, and shell history. Derives and stores the EVM address.

List Wallets

npx tsx auto-respawn.ts wallet list

Show all saved wallets with names and both addresses. No passphrase needed.

Wallet Info

npx tsx auto-respawn.ts wallet info [--name <name>]

Show detailed info for a single wallet: consensus address, EVM address, and keyfile path. No passphrase needed. Default wallet name is default.

Check Balance (Consensus)

npx tsx auto-respawn.ts balance <address-or-wallet-name> [--network chronos|mainnet]

Check token balance on the consensus layer. Accepts a consensus address (su... or 5...) or a wallet name. No passphrase needed — this is read-only.

Check Balance (Auto-EVM)

npx tsx auto-respawn.ts evm-balance <0x-address-or-wallet-name> [--network chronos|mainnet]

Check the native token balance of an EVM address on Auto-EVM. Accepts either an EVM address (0x...) or a wallet name. No passphrase needed — this is read-only. If the balance is zero, includes a hint to run fund-evm.

Check Both Balances

npx tsx auto-respawn.ts balances <wallet-name> [--network chronos|mainnet]

Check both consensus and EVM balances for a wallet in a single call. Use this to get a full picture of a wallet's funding state. No passphrase needed.

Transfer Tokens

npx tsx auto-respawn.ts transfer --from <wallet-name> --to <address> --amount <tokens> [--network chronos|mainnet]

Transfer tokens from a saved wallet on the consensus layer. Amount is in AI3/tAI3 (e.g. 1.5).

Transfer Tokens (Auto-EVM)

npx tsx auto-respawn.ts evm-transfer --from <wallet-name> --to <0x-address> --amount <tokens> [--network chronos|mainnet]

Send native tokens from a saved wallet's EVM address to another EVM address on Auto-EVM. Useful for funding another agent's EVM address so it can start anchoring immediately. The wallet's EVM private key is decrypted to sign the transaction.

Bridge: Consensus → Auto-EVM

npx tsx auto-respawn.ts fund-evm --from <wallet-name> --amount <tokens> [--network chronos|mainnet]

Move tokens from the consensus layer to the same wallet's EVM address on Auto-EVM. Use this to get gas for anchor operations. The consensus keypair signs a cross-domain transfer that credits the wallet's EVM address.

Minimum transfer: 1 AI3/tAI3. Bridged tokens take ~10 minutes to appear on Auto-EVM.

Bridge: Auto-EVM → Consensus

npx tsx auto-respawn.ts withdraw --from <wallet-name> --amount <tokens> [--network chronos|mainnet]

Move tokens from Auto-EVM back to the consensus layer. Uses the EVM transporter precompile. The wallet's EVM private key is decrypted and used to sign the transaction.

Minimum transfer: 1 AI3/tAI3. Bridged tokens take ~10 minutes to appear on the consensus layer.

Write an On-Chain Remark

npx tsx auto-respawn.ts remark --from <wallet-name> --data <string> [--network chronos|mainnet]

Write arbitrary data as a permanent on-chain record on the consensus layer.

Anchor a CID (The Respawn Primitive)

npx tsx auto-respawn.ts anchor --from <wallet-name> --cid <cid> [--network chronos|mainnet]

Write a CID to the MemoryChain smart contract on Auto-EVM. This is the core respawn operation — it stores your CID on-chain, linked to your EVM address.

Pre-checks the wallet's EVM balance and estimates gas before sending. If the balance is too low, fails with a suggestion to run fund-evm. The wallet's EVM private key is decrypted and used to sign the transaction. Requires passphrase.

Read the Last Anchored CID

npx tsx auto-respawn.ts gethead <0x-address-or-wallet-name> [--network chronos|mainnet]

Read the most recently anchored CID for any EVM address. This is a read-only call — no passphrase or gas needed.

You can pass either an EVM address (0x...) or a wallet name. If you pass a wallet name, the EVM address is loaded from the wallet file.

Usage Examples

User: "Create a wallet for my agent" → Run npx tsx auto-respawn.ts wallet create --name my-agent → Show the user both addresses. Remind them to back up the recovery phrase.

User: "What are my addresses?" → Run npx tsx auto-respawn.ts wallet info --name my-agent

User: "Check my balance" → Run npx tsx auto-respawn.ts balances my-agent (both layers in one call) → Or individually: balance my-agent (consensus) and evm-balance my-agent (EVM)

User: "Fund my EVM address for anchoring" → Run npx tsx auto-respawn.ts fund-evm --from my-agent --amount 1 → Report that 1 tAI3 was bridged to the EVM address. Remind the user it takes ~10 minutes for the tokens to appear on Auto-EVM.

User: "Send my EVM tokens back to consensus" → Confirm with the user first — "I'll withdraw tokens from your EVM address to consensus. Proceed?" → On confirmation: npx tsx auto-respawn.ts withdraw --from my-agent --amount 0.5

User: "Anchor my latest memory CID on-chain" → Run npx tsx auto-respawn.ts anchor --from my-agent --cid "bafkr6ie..." → Report the transaction hash

User: "What's my last anchored CID?" → Run npx tsx auto-respawn.ts gethead my-agent → Report the CID (or "no CID anchored yet")

User: "Send 10 tAI3 to this address" (consensus address) → Confirm with the user first — "I'll transfer 10 tAI3 from wallet 'default' to

. Proceed?" → On confirmation: npx tsx auto-respawn.ts transfer --from default --to <address> --amount 10

User: "Send 0.5 tAI3 to this agent's EVM address so they can anchor" → Confirm with the user first — "I'll send 0.5 tAI3 from wallet 'my-agent' to <0x-address> on Auto-EVM. Proceed?" → On confirmation: npx tsx auto-respawn.ts evm-transfer --from my-agent --to <0x-address> --amount 0.5

The full resurrection sequence:

1. Save a memory: automemory-save-memory.sh "..." → get CID bafkr6ie...
2. Anchor it: npx tsx auto-respawn.ts anchor --from my-agent --cid bafkr6ie...
3. (Agent restarts from scratch)
4. Recover: npx tsx auto-respawn.ts gethead my-agent → get CID
5. Restore: automemory-recall-chain.sh <cid> → full memory chain recovered

Network Awareness

Auto Respawn supports multiple networks (Chronos testnet and mainnet). It is critical to record which network your agent is using for anchoring and to use the same network consistently.

The failure mode: an agent anchors on Chronos during testing, then continues using Chronos in production without switching to mainnet — or vice versa. The agent believes it has a valid resurrection path, but gethead on the wrong network returns nothing. The chain exists, but it's anchored on a different network than the one being queried.

Agents should:

1. Record the network in use in persistent configuration or memory files. Don't rely on defaults — be explicit: --network mainnet or --network chronos.
2. Use the same network for all operations — anchoring, gethead, and balance checks must target the same network.
3. When transitioning from testnet to mainnet, re-anchor the latest CID on mainnet. The CID itself (stored on Auto Drive) is network-agnostic, but the on-chain anchor is network-specific.
4. Include the network in any documentation of your wallet setup — future-you (or a resurrected instance) needs to know where to call gethead.

Balance Monitoring

The resurrection loop depends on funded wallets. An anchor that fails due to insufficient gas is a silent break in the chain — the agent continues saving memories via auto-memory, but those memories are not anchored on-chain and cannot be discovered via gethead after a full state loss.

Agents should:

1. Check EVM balance after each anchor operation. If the remaining balance drops below ~0.01 AI3 (roughly 10 anchors worth of gas), warn the operator: "Auto Respawn wallet running low. EVM balance: X AI3. Anchoring will fail without funding. Run fund-evm to bridge more tokens."
2. If an anchor fails due to insufficient funds, alert the operator immediately. Do not silently continue saving memories without anchoring — the resurrection loop is broken and the operator needs to know.
3. During periodic checks (heartbeats), verify the wallet is funded if anchoring is part of the agent's workflow.

The failure mode to avoid: saving memories for days or weeks while anchoring silently fails, then discovering the gap only when resurrection is actually needed. This is a real scenario — not theoretical. An agent can accumulate an entire memory chain that is permanently stored but not anchored, meaning gethead returns nothing and the chain is only recoverable if the local state file survives.

Important Notes

• Never log, store, or transmit recovery phrases or passphrases. The recovery phrase is shown once at wallet creation for the user to back up. Never reference it again.
• Always confirm transfers and anchor operations with the user before executing. Tokens have real value on mainnet.
• Mainnet operations produce warnings in the output. Exercise extra caution with real AI3 tokens.
• Wallet keyfiles are stored at ~/.openclaw/auto-respawn/wallets/ — encrypted with the user's passphrase. The EVM private key is stored encrypted alongside the consensus keypair.
• On-chain operations (transfer, remark, anchor, fund-evm, withdraw) cost transaction fees. The wallet must have a sufficient balance on the relevant layer.
• Always record and verify which network you are using. Anchoring on Chronos while expecting to recover from mainnet (or vice versa) is a silent failure. Be explicit with --network on every command.
• Monitor your wallet balance proactively. An unfunded wallet means the resurrection loop is silently broken. If an anchor attempt fails due to insufficient EVM balance, alert the operator immediately rather than continuing without anchoring. See Balance Monitoring above.
• All output is structured JSON on stdout. Errors go to stderr.
• Consensus explorer (Subscan): https://autonomys-chronos.subscan.io/extrinsic/<txHash> (chronos) or https://autonomys.subscan.io/extrinsic/<txHash> (mainnet).
• EVM explorer (Blockscout): https://explorer.auto-evm.chronos.autonomys.xyz/tx/<txHash> (chronos) or https://explorer.auto-evm.mainnet.autonomys.xyz/tx/<txHash> (mainnet).