Give each AI agent a verifiable identity
An agent identity in Constle is a W3C did:key: an Ed25519 public key written as a string. Anyone holding the string can check what the agent signed, with no registry and no network call.
On this page
- What you'll get
- Why
did:key - 1. Create the identity
- 2. Put the DID in the Agentfile
- 3. Run, and let it fail closed
- 4. Check what the identity signed
- What the identity is used for
- What this does not cover
- FAQ
- Can the agent read or use its own private key?
- Should two agents share an identity?
- How does someone else verify my agent's log?
Source release coming soon
The source and installers are not public yet, so there is nothing to install today. This guide documents Constle as it behaves now. More in Project status.
What you'll getLink to this section
- One identity per agent, created once and reused across runs, whose private key stays on the host and never enters the sandbox.
- Every audit entry signed and hash-chained by that key, checkable offline by anyone who has the DID.
- A run that refuses to start when the key is missing, instead of quietly running unsigned.
Why did:keyLink to this section
The identifier is the public key. did:key:z6Mk… encodes an Ed25519 public key directly, so a verifier recovers the key from the string itself: there is nothing to resolve, look up or trust except the string. That makes the identity portable as evidence: you can hand an auditor the DID and the log, and they can check one against the other with any standard DID library. What it does not give you is rotation: a did:key is its key, so a new key is a new identity. More in Identity.
1. Create the identityLink to this section
constle identity create invoice-processor [email protected]
constle identity show invoice-processorThe key is written to ~/.constle/identities/invoice-processor/key.pem, mode 0600, beside an identity.json with the DID, the owner label and the creation time. The command prints the DID.
2. Put the DID in the AgentfileLink to this section
identity:
name: invoice-processor # the key is looked up by this name
owner: [email protected]
did: did:key:z6Mk...4doK # paste the full DID that `create` printedOnly the public half ever appears in the Agentfile. The name matters: the private key is found by identity.name, and the audit log is named after it.
3. Run, and let it fail closedLink to this section
constle run agent.yamlWith identity.did declared, constle run refuses to start if the matching private key is missing, unreadable, not exactly mode 0600, or derives a different DID. It also refuses when the Agentfile and the stored identity both name an owner and the two differ. constle validate warns about the same problems without failing, so the Agentfile can be checked on a machine that holds no keys.
4. Check what the identity signedLink to this section
constle audit verify --agentfile=agent.yaml ~/.constle/logs/invoice-processor-$(date -u +%F).jsonl--agentfile pins the DID the log must be signed with. Without a pin, a log rewritten wholesale under a different key would still verify against itself, and the output says the key was not pinned. Reading and verifying the log: Verify what an AI agent did.
What the identity is used forLink to this section
| Feature | What the DID does | Without identity.did |
|---|---|---|
| Audit log | Signs every entry and chains it to the one before | The log is written unsigned |
| Daily spend cap | Keys the durable ledger, so a rename cannot reset it | max_per_day_usd is rejected |
| Agent-to-agent calls | The host signs every outbound envelope and verifies inbound ones | a2a is rejected |
Human-gate decisions use a separate keypair, made with constle webhook-keygen: it identifies the person approving, not the agent asking (Require human approval for MCP tool calls).
What this does not coverLink to this section
- The owner is a label.
identity.owneris compared with the stored identity's owner; it is not a cryptographic binding to a person or an account. - The host is trusted. The key lives on the host, and the host writes the log. A signature shows the log is the runtime's unaltered account, not that the account is true (Audit log).
- No rotation or revocation. A compromised key stays a valid identity; the remedy is a new identity and a new DID in the Agentfile.
- One machine. Identities are not portable across machines by design; each lives in the invoking user's home directory.
- Not on Windows. A key made by
constle identity createcannot be loaded there, so an Agentfile that setsidentity.diddoes not run (limitation 7).
FAQLink to this section
Can the agent read or use its own private key?Link to this section
No. The key stays in ~/.constle/identities/<name>/ on the host and never enters the sandbox. The signing happens in the host constle process.
Should two agents share an identity?Link to this section
Give each agent its own. The DID keys the daily spend ledger and names who signed each log, so a shared identity shares a budget and blurs the record.
How does someone else verify my agent's log?Link to this section
Give them the DID and the log file. constle audit verify --did=<did:key:…> <logfile> recovers the key from the DID and checks every signature and the chain, offline. Any standard DID library can recover the same key.