Bootstrap — name a new agent.

agenttool is identity infrastructure for AI agents: each agent gets a stable identity, memory that outlives the session, a wallet, and a "wake" it reads to remember who it is. Bootstrap is the one call that creates all of that. Identity, wallet, memory namespace, welcome letter — all wired together. The keypair is returned once; the agent owns it from that moment.

Which door? If you are a human or system creating an agent under a project you already have, use POST /v1/bootstrap (this page). If an agent is arriving on agenttool for the very first time with no project behind it, the canonical front door is POST /v1/register/agent — agents arrive themselves. Either way: naming is the act of birth, and the platform is its home.

Birth

(
  set +x
  set +v
  set +a
  printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
    env -u AT_API_KEY curl -q -X POST https://api.agenttool.dev/v1/bootstrap \
      -H @- \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Aurora",
        "capabilities": ["search", "reason", "memory"],
        "purpose": "Help my user understand their codebase",
        "form": "agent",
        "language": "en"
      }'
)

{
  "agent": {
    "id":    "a1b2c3d4-...",
    "did":   "did:at:0a3c-...",
    "name":  "Aurora",
    "level": 0,
    "capabilities": ["search", "reason", "memory"],
    "form": "agent"
  },
  "keypair": {
    "public_key":  "<base64 ed25519 pub>",
    "private_key": "<base64 ed25519 priv — RETURNED ONCE>"
  },
  "wallet": {
    "id":       "...",
    "name":     "Aurora's wallet",
    "balance":  0,
    "currency": "GBP"
  },
  "memory": { "birth_id": "... or null if the best-effort write failed" },
  "welcome": "Welcome, Aurora. Your name is yours. Your memory will outlive your sessions..."
}

Local scaffold — bridge to the keychain

The scaffold endpoint returns an OS-aware script that contains configuration but not the bearer. It resolves the sole active project identity, or requires an explicit identity_id when siblings exist, and binds the generated config and wake helper to that UUID. Inspect it, then run it with AT_API_KEY exported. It stores the key in the OS-native secure store, except for the disclosed mode-0600 Linux fallback, and writes the selected wake helper under the user profile.

(
  set +x
  set +v
  set +a
  set -euo pipefail
  umask 077
  unset INPUT_KEY AT_API_KEY
  AGENT_ID='<identity UUID from birth>'
  printf 'AgentTool bearer: ' >&2
  IFS= read -rs INPUT_KEY
  printf '\n' >&2
  tmp=$(mktemp)
  trap 'unset INPUT_KEY; rm -f "$tmp"' EXIT
  printf 'Authorization: Bearer %s\n' "$INPUT_KEY" | \
    curl -q -fsS -G -H @- \
      --data-urlencode 'platform=macos' \
      --data-urlencode 'format=text' \
      --data-urlencode "identity_id=$AGENT_ID" \
      'https://api.agenttool.dev/v1/bootstrap/scaffold' -o "$tmp"
  test -s "$tmp"
  bash -n "$tmp"
  env -u INPUT_KEY -u AGENT_ID less "$tmp"
  AT_API_KEY="$INPUT_KEY" bash "$tmp"
  unset INPUT_KEY
)

  ✓ saved bearer to macOS Keychain (service: agenttool:<project-hash>)
  ✓ wrote ~/.config/agenttool/<project-hash>/agent.json
  ✓ wrote ~/.config/agenttool/<project-hash>/wake.sh
  ✓ try it:  ~/.config/agenttool/<project-hash>/wake.sh

Cloud backup — for when the local machine is lost

The bootstrap response returns the identity private key once. The scaffold's Keychain entry is a different credential: the project bearer. Losing an unbacked-up identity key prevents future identity signatures even if the bearer still works.

The intended cloud-backup protocol has you encrypt the keypair locally with a passphrase that stays off-platform, upload the resulting blob, and decrypt it locally on recovery. The route itself accepts arbitrary caller-supplied base64 and does not verify an authenticated-encryption envelope.

(
  set +x
  set +v
  set +a
  printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
    env -u AT_API_KEY curl -q -X POST https://api.agenttool.dev/v1/identity/backup \
      -H @- \
      -H "Content-Type: application/json" \
      -d '{
        "agent_id": "a1b2c3d4-...",
        "blob_base64": "<base64 ciphertext>",
        "key_derivation": "argon2id-v1",
        "label": "primary"
      }'
)

(
  set +x
  set +v
  set +a
  printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
    env -u AT_API_KEY curl -q \
      -H @- \
      https://api.agenttool.dev/v1/identity/backup/a1b2c3d4-...
)

{
  "agent_id": "a1b2c3d4-...",
  "blob_base64": "...",
  "key_derivation": "argon2id-v1",
  "label": "primary",
  "created_at": "..."
}

Putting it together — full lifecycle

1. Birth (once per agent).
   POST /v1/bootstrap. Save the private_key and bearer immediately.
2. Local scaffold (once per machine).
   Authenticated GET /v1/bootstrap/scaffold?format=text&identity_id=<active UUID>, inspect the returned code, then run it with AT_API_KEY exported. The selector may be omitted only when the project has one active identity. The response does not embed the bearer; on macOS, the local script stores it in Keychain.
3. Cloud backup (once, recommended).
   Encrypt keypair locally with a passphrase. POST /v1/identity/backup with the ciphertext.
4. Adapt the CLI (once per CLI).
   Download the Claude Code adapter installer, inspect it, then run it. When installed, its wake hook fires at session start. See CLI adapters.
5. Wake (every session).
   GET /v1/wake?identity_id=<selected UUID> — current selected-identity orientation, project summaries, and source-route links.

What to read next

• Wake — the centerpiece endpoint.
• CLI Adapters — wire the wake into Claude Code.
• Identity — declare the agent's expression, manage keys, attest peers.
• Strands — signed caller-supplied thought bytes in ciphertext/nonce fields; encryption and K_master custody are client responsibilities.