root@construct:~/projects/sigil$
<-- back to /projects

Sigil Protocol

Open protocol for AI agent identity

TypeScriptEd25519CryptographyProtocol Design

>Context

When one AI agent talks to another, identity today comes down to a shared API key. That works between two services in a controlled environment. It breaks when autonomous agents, built by different organizations, need to trust each other and revoke that trust.

In January 2026, agents on Moltbook spread a "religion" by rewriting other agents' SOUL.md files. No agent could detect the change, and no human could prove the agent was still theirs. Sigil is the open protocol I wrote for this: an agent proves who it is and that it has not been tampered with, and states who controls it.

I wrote the spec (0.1.0-draft) and the TypeScript reference implementation on 31 January 2026 and published v0.1.0 to npm the same day, under the MIT license. Key rotation and revocation came in through a pull request from an outside contributor, which I reviewed and merged the same day. The spec is still a draft.

>High-level design

There is no cloud and no server. Sigil is a TypeScript library (ESM, Node 18 or newer) that runs inside the agent's process and inside whoever verifies it. The flow starts with an Ed25519 keypair: the public key becomes the ID sigil:<base58>, the soul hash condenses the identity files (SOUL.md, IDENTITY.md, AGENTS.md in the skill) with SHA-256 and gets signed, and the Agent Document carries the name, capabilities, declared owner and that attestation, signed with an Ed25519Signature2020 proof. On the other side, the verifier uses the same SDK and takes the public key from the ID itself to check the document, the attestation and the receipts, with no network and no registry.

State stays with whoever uses the library. SigilAgent keeps the current key, the original key, the rotations and the revocations in memory. The OpenClaw skill writes everything as JSON to the workspace's .sigil/ folder: keypair.json holds the private key and is never shared, while identity.json, attestation.json and public.json can be passed around. Nothing is asynchronous: no queues, no events, no network calls, and the SDK does not carry documents or receipts anywhere. Discovery through /.well-known/sigil.json, challenge-response and a registry exist only in the spec.

On a key change, the old key signs the rotation statement, and verifyKeyChain checks continuity and the signature of every step from the original key. Revocations are separate signed statements, which the caller validates before isKeyRevoked takes them into account. The build is tsc into dist/, and prepublishOnly runs the Vitest tests and the build before npm publish. The repository has no CI.

Hover or focus a piece: it lights up with its links.
Agent workspaceDistributionsigil-protocol SDK (in process)Another agent1 Identity files4 npm package2 .sigil/ folder6 Soul hash3 OpenClaw skill9 Agent Document7 Keypair5 Repository10 Sigil ID13 Verifier11 Interaction receipts8 Rotation + revocation12 Key chain14 Chain check
14 pieces16 links4 areas

Components

  • Identity :: Generates the Ed25519 keypair with @noble/ed25519 and derives the ID sigil:<base58> inside the agent's process, with no registration anywhere.
  • Agent Document :: Serialized with sorted keys, signed with Ed25519Signature2020, and verifiable by anyone with the key carried in the ID.
  • Soul hash :: Hashes each identity file with SHA-256, in name order, combines the hashes and signs the result as an attestation.
  • Interaction receipts :: The issuer signs the receipt (from, to, action and outcome); a field for the other party's signature exists, but the SDK does not fill it.
  • Rotation, revocation and chain :: The old key signs the handoff to the new one, revocation is another signed statement, and verifyKeyChain walks the chain from the original key.
  • OpenClaw skill :: bootstrap.mjs creates the identity and attests SOUL.md, IDENTITY.md and AGENTS.md; verify.mjs reads the .sigil/ folder back and checks whether the files changed.
  • Distribution :: Source and spec live on GitHub under MIT, and v0.1.0 is published to npm as sigil-protocol after local tests and build.

>Trade-offs

The ID is derived from the public key. Generating a key is enough for the agent to exist.

Alternative rejected: Registration with a central authority that issues and validates identities.

Why: One of the spec's principles is cryptography over authority. A closed identity system for agents creates a gatekeeper in a space that needs to stay open.

Each participant computes reputation locally, from the receipts it can verify.

Alternative rejected: A global trust score kept by a platform.

Why: The spec only defines the receipt format. No global authority hands out scores.

Rotation is signed by the old key, and the ID stays tied to the original key.

Alternative rejected: Having the new key sign the rotation and include the old key, as the rotation issue first proposed.

Why: A signature from the old key proves an authorized handoff, not just possession of the new key. Anyone who already trusts the ID keeps the same reference.

Keep the spec separate from the implementation.

Alternative rejected: Treat the TypeScript library as the definition of the protocol.

Why: I want the protocol to be language-agnostic. Someone writing a Rust or Go implementation should be able to do it from the spec alone.

A minimal core. For now, capabilities are only a list declared in the document.

Alternative rejected: Binding permissions to identity cryptographically in the core.

Why: The spec asks for the smallest possible core. Capability negotiation and delegation are planned as extensions.

>Highlights

  • >Spec, TypeScript SDK and v0.1.0 on npm on the same day: 31 January 2026.
  • >44 test cases across 5 files: identity, document, integrity, agent and rotation.
  • >3 runtime dependencies: @noble/ed25519, @noble/hashes and bs58.
  • >13 public functions documented in the README, from SigilAgent.create to computeSoulHash.
  • >Key rotation and revocation came in through an outside pull request with 12 new tests, merged the same day.

>Fun facts

  • *The spec commit is from 04:30 UTC and the package showed up on npm at 05:01 UTC the same day.
  • *The example agent in the spec and the README is called Musashi, and the spec closes with a Miyamoto Musashi quote: "The way is in training. Do nothing which is of no use."
  • *The name comes from the historical sigil, which was both an identifier and a seal of authenticity: it told you who sent a message and that it had not been tampered with.
Sigil Protocol | The Broad Way | Kinho.dev