Here is Free2PA installed in Hello World.

The demo is a normal tiny agent with one control file: SOUL.md. Free2PA is installed at the read path, so SOUL.md is verified before its text can become model instructions.

Open the GitHub repo → Download the package →

The files added to Hello World

The app still reads Markdown. Free2PA adds a signed receipt and a local trust group beside the demo.

public/demo/hello-agent/
  trusted/
    SOUL.md
    SOUL.md.c2pa.json
  changed/
    SOUL.md
    SOUL.md.c2pa.json
  trusted-publishers/
    hello-group.crt
    local-console.crt

The install steps

Install the packageAdd Free2PA to the app so the loader can import the verifier.

Create a publisher keyThe private key signs reviewed control files. It stays out of version control.

Trust the publisher certificateThe public certificate goes in this app's trusted-publishers directory.

Sign SOUL.mdFree2PA writes SOUL.md.c2pa.json beside the approved file.

Verify before model contextThe app calls the load gate before passing SOUL.md to the model.

Install and sign

This is the generic command sequence for a Hello World-style app.

npm install --save-dev \
  https://github.com/kilroyblockchain/free2pa-devtool/releases/download/v0.4.2/free2pa-0.4.2.tgz

npx free2pa keygen \
  --name "Hello World Publisher" \
  --id hello-world \
  --out-dir .free2pa/private

npx free2pa trust add \
  .free2pa/private/hello-world.crt \
  --store .free2pa/trusted-publishers \
  --id hello-world

npx free2pa sign agent/SOUL.md \
  --cert .free2pa/private/hello-world.crt \
  --key .free2pa/private/hello-world.key

Wire the load gate

Hello World's server calls the gate before starting the model call.

import { loadVerifiedFile } from 'free2pa/load-gate';

async function runHelloWorldAgent({ assetPath, trustStore }) {
  const verifiedSoul = await loadVerifiedFile({
    assetPath,
    trustStore,
  });

  return startAgent(verifiedSoul);
}

await runHelloWorldAgent({
  assetPath: 'public/demo/hello-agent/trusted/SOUL.md',
  trustStore: 'public/demo/hello-agent/trusted-publishers',
});

What the Hello World install proves

If SOUL.md changes without a new trusted signature, the file no longer matches its receipt. Free2PA rejects the edit before model context. If the local console signs the edit, the new receipt verifies and the edited control file becomes the approved version.

Add a team member

Each person who is allowed to approve agent control files gets their own publisher keypair. They generate it locally and upload only the public certificate.

npx free2pa keygen \
  --name "Ava from Agent Team" \
  --id ava \
  --out-dir .free2pa/private

# Ava shares this file with the project:
.free2pa/private/ava.crt

# Ava does not upload this file:
.free2pa/private/ava.key

Trust or remove that publisher

The verifier trusts public certificates in the local trust group. Adding a certificate lets that teammate sign reviewed control files. Removing it stops future approvals from that publisher.

npx free2pa trust add ava.crt \
  --store .free2pa/trusted-publishers \
  --id ava

npx free2pa sign agent/SOUL.md \
  --cert .free2pa/private/ava.crt \
  --key .free2pa/private/ava.key

npx free2pa trust remove ava \
  --store .free2pa/trusted-publishers

Verify the install without a model account

The example runner has a deterministic fake model so you can test the load gate before configuring OpenAI or Azure OpenAI.

npm run demo:hello -- trusted block --fake-model
npm run demo:hello -- changed block --fake-model
npm run demo:hello -- changed repair --fake-model