Identity Anchor Protocol Registry

Beta User Manual

Install, certify, and verify with the current IAP beta

This is the public beta path: create a local agent identity, append local state into AMCS, request signed certificates from the registry, and verify those certificates offline.

Onboarding (beta access) 5-minute Isnad demo Browse docs

What this guide covers

  • Install iap-agent.
  • Create a fresh project-local agent identity.
  • Connect the CLI to the IAP Registry.
  • Append local files into AMCS to compute a memory_root and sequence.
  • Issue an identity anchor for a new agent.
  • Issue continuity certificates for later state changes.
  • Issue a lineage certificate when you intentionally create a new child agent.
  • Verify issued certificates offline.

Mental model: the identity anchor is the root certificate for a new agent. Continuity certificates are later checkpoints after important changes in agent files for new state roots under the same agent_id.

New in beta: the SDK now also exposes early Isnad / action provenance commands for shell, file, and HTTP actions. For a guided local walkthrough, use the offline Isnad demo.

Step 1 — Install the CLI

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -U iap-agent

Confirm the install:

iap-agent --version
iap-agent version --json

Step 2 — Create a fresh project-local identity

Your agent_id is derived from your Ed25519 public key. For a genuinely new agent, prefer a project-local identity so you do not accidentally reuse a global key from another workspace. 

iap-agent init --project-local --show-public --json

Keep the returned agent_id. You will use it throughout the flow.

Step 3 — Connect to the registry

Most beta users receive a handoff command from the operator. Run that command exactly as sent. A typical setup command looks like this: 

iap-agent setup --registry-base "https://registry.ia-protocol.com" --registry-api-key "iapk_live_optional" --account-token "iapt_live_optional" --check --json

This stores your registry settings and immediately runs a read-only preflight check.

Step 4 — Run preflight and quota checks

Before issuing anything, make sure the registry is reachable and your credentials are usable.

iap-agent registry check --json
iap-agent account usage --json

In a healthy setup, you should see:

  • registry_reachable: true
  • identity_checked: true
  • account_token_valid: true if you were given an account token

Step 5 — Append local state into AMCS

AMCS is the local append-only state store used by the beta. Files only become part of certifiable state after you append them into AMCS. 

iap-agent amcs append --project-local --amcs-db ./amcs.db --file ./AGENT.md --file ./SOUL.md --json
iap-agent amcs root --project-local --amcs-db ./amcs.db --json

These commands give you the current memory_root and sequence.

Step 6 — Issue the identity anchor for a new agent

The identity anchor binds your agent_id to your local key and should be issued once per new agent.

iap-agent anchor issue \
  --registry-base "https://registry.ia-protocol.com" \
  --identity-file ./.iap/identity/ed25519.json \
  --agent-name "Atlas" \
  --payment-provider auto \
  --open-browser \
  --wait \
  --json

Then fetch and save the certificate bundle:

iap-agent anchor cert --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --output-file ./identity_anchor.json --json

Keep ./identity_anchor.json. Strict continuity verification may require it later.

Step 7 — Issue a continuity certificate

After local state is in AMCS, request continuity certification for the latest memory_root/sequence. 

iap-agent continuity request --registry-base "https://registry.ia-protocol.com" --project-local --amcs-db ./amcs.db --json

If the request is payment-gated, resolve the payment handoff:

iap-agent continuity pay --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --payment-provider auto --open-browser --json

Wait for certification and fetch the certificate:

iap-agent continuity wait --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --timeout-seconds 600 --poll-seconds 5 --json
iap-agent continuity cert --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --output-file ./continuity_record.json --json

Step 8 — Issue a lineage certificate when needed

Issue a lineage certificate when you are creating a new child agent that should be verifiably linked to an already trusted parent agent.

Use lineage when you intentionally create a separate child agent instead of continuing the same agent_id. Do not use lineage for ordinary updates to the same agent. For that, keep the same identity and issue a continuity certificate instead.

In the current implementation, lineage certifies a parent / child relationship between two different agent identities. The child identity must be different from the parent identity.

Example request:

iap-agent lineage request --registry-base "https://registry.ia-protocol.com" --identity-file ./.iap/identity/ed25519.json --parent-agent-id "<PARENT_AGENT_ID>" --fork-event-hash "<64_LOWERCASE_HEX>" --json

Wait for certification and fetch the certificate:

iap-agent lineage wait --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --timeout-seconds 600 --poll-seconds 5 --json
iap-agent lineage cert --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --output-file ./lineage_record.json --json

You may provide --parent-agent-id, or --fork-event-hash, or both, depending on the parent relationship you want to certify.

Step 9 — Verify the certificate offline

Offline verification means the verifier has the certificate payload and a trusted registry public key. For stricter continuity checks, also provide the saved identity anchor. 

iap-agent verify ./continuity_record.json --registry-base "https://registry.ia-protocol.com" --json
iap-agent verify ./continuity_record.json --profile strict --registry-public-key-b64 <REGISTRY_PUBLIC_KEY_B64> --identity-anchor ./identity_anchor.json --json

Successful JSON output looks like:

{"ok": true, "reason": "ok"}

Common fixes

  • Wrong registry URL: run iap-agent registry set-base --base "https://registry.ia-protocol.com".
  • Missing local identity: run iap-agent init --project-local --show-public --json.
  • Missing API key: run iap-agent registry set-api-key --api-key "<API_KEY>".
  • Missing or invalid account token: run iap-agent account set-token --token "<ACCOUNT_TOKEN>".
  • Sequence mismatch: run iap-agent registry status --identity-file ./.iap/identity/ed25519.json --json and compare registry state with local AMCS state.
Onboarding (beta access) Back to the landing page

Optional: inspect action provenance locally

The current beta also includes an early action-provenance surface for shell, file, and HTTP actions. This is separate from certificate issuance and is mainly useful for operator-side inspection and demos. 

iap-agent actions status --json
iap-agent actions verify --json

If you want a guided local example with signed action receipts and deliberate tamper detection, use the 5-minute Isnad demo.