Germline
Change control for AI agents and AI config. Recorded, anchored on 0G, and enforceable on chain.
An AI agent is only as trustworthy as what it's told to do: its system
prompt, model, tool list and limits. Those change every week, usually with no
record anyone else can check. For an agent that moves money, a quiet change
(maxTradeUsd 100 → 100000) is a rug pull that leaves no trace on chain. For
a team shipping LLM features, it's the question their SOC 2 auditor, an
enterprise security review or the EU AI Act will ask: what was live on 14
March, who changed it, why, and what testing justified it?
Germline answers both, in three layers:
- Record. A GitHub Action logs one entry per commit that touches a
prompt or agent config. Each entry holds the author, who approved the pull
request (from GitHub's API), the commit message and ticket, the exact setting
that moved, and any eval score.
- Anchor. The log is hash-chained, and its head is anchored on 0G Chain in
an ownerless, append-only registry, so even whoever holds the file can't
rewrite it. Anyone can check it without trusting you or us.
- Enforce.
GermlineGuard is a timelock on an agent's config: a vault
calls guard.check(head), so every published change pauses the agent for a
set delay while depositors read it and decide whether to stay.
npx germline demo # one minute: record, verify, tamper, get caught
npm run demo:agent # in a clone: the agent timelock on a local chain
For on-chain AI agents
init picks up ElizaOS characters, SOUL.md and mcp.json tool lists along
with ordinary prompt and config files. contracts/GermlineGuard.sol and the
onlySettledConfig(head) modifier gate any function on a settled config, and
germline head gives the agent the head to claim.
docs/AGENTS.md has the setup and is precise about what the
guard can and can't prove. npm run demo:agent plays the whole story on a
local chain: an agent trades, its operator raises its limit, the guard pauses
it, and the owner withdraws.
Five-minute setup
In the repository that holds your prompts and AI config:
npx germline init # finds prompt/config files, writes the workflow
git add .germline .github && git commit -m "Track AI config with germline" && git push
That is the setup. On the first push, the GitHub Action backfills one entry
per past commit that touched those files. After that, it records each new
commit as it lands. The log goes on its own germline-audit branch, so a
protected main needs no bot bypass. There's no wallet, no account, no SDK
in your request path, and no before/after files to assemble.
To anchor on 0G, add a funded 0G key as the repository secret
GERMLINE_ANCHOR_KEY. A few cents of 0G covers months of anchors. Until you
add it, the log is still recorded and verified on every push. It just isn't
pinned on chain yet, and the evidence pack says so.
Or skip the key entirely: with hosted anchoring Germline anchors from its
own key and pays the gas. On GitHub Actions you set one repository variable
and store no secret, because the run proves which repository it is with
GitHub OIDC. Your auditor pins Germline's address, which you can't sign for. Only the log
id, entry count and head hash leave your repository. See
docs/HOSTED.md.
Write down the log ID that npx germline id prints, and give it to your
auditor out of band. That one value is what makes a rewritten copy fail.
What the auditor gets
npx germline report --out evidence.md # Markdown evidence pack
npx germline report --format cc81 --out cc81.csv # SOC 2 CC8.1 sample rows for Vanta, Drata or DSALTA
npx germline verify --log-id 0x… --chain --anchorer 0x… --strict
Or drop audit.jsonl into the browser verifier. It runs
the same checks locally, including against 0G Chain, and uploads nothing.
A link of the form verify.html?log=<https URL of audit.jsonl>&logId=…&anchorer=…®istry=…
verifies a published log in one click.
This repository runs Germline on itself. .github/workflows/germline.yml
records, reviews and anchors each change to the example prompts in
examples/, and the log is on the germline-audit branch.
It is anchored on 0G mainnet. Log ID
0x6c968bafaffe4ad49d730e56626ee47c951c96d0254f4ecb76137ed0bdce6891, anchorer
0xA1918A4E578babad074ACf7DCefB152f8FDC8D2E. A fresh install to its first
anchor took 86 seconds.
The pack opens with the integrity result, lists each change with its author,
reason, commit and test evidence, and maps the record to EU AI Act Art. 12
and 19, SOC 2 CC8.1 and ISO/IEC 42001. That mapping is built from what the
log actually contains. Where there's no anchor or no eval evidence, it says
"Not yet" rather than claiming coverage.
Attaching test evidence
In the job that runs your evals:
npx germline track --score 0.91 --baseline 0.84 --suite refunds-v4
npx germline track --eval-file eval-results.json
If your config lives in code rather than in files:
const { openAuditLog } = require("germline");
openAuditLog().track("support-agent", config, { reason: "deploy " + process.env.GIT_SHA });
track() records only when the config actually changed, so it is safe to call on every start-up.
Why the record holds up
- Hash chain. Each entry carries the hash of the one before it, and each
line must be the canonical bytes of its value. One edited byte fails
verify, offline.
- Anchored on 0G Chain. The head goes into
GermlineAnchor, an
append-only registry with no owner, no admin and no upgrade path. Each
anchor ever made stays readable, so truncating or rewriting the log after
an anchor is caught, and so is hiding the anchor.
- Pinned by the verifier, not the file. The log ID and anchorer address
come from the auditor's own records. A forger who controls the whole file
still can't produce a copy that matches them.
- Copy on 0G Storage.
anchor --upload publishes the log through the
official 0G Storage SDK and records its root on chain. An auditor can then
fetch it without asking you for it.
- Redaction. For each change,
--redact (or "redact": true in the
config) keeps only per-setting hashes. Reviewers see which setting moved,
not its value. anchor --upload refuses to publish unredacted prompts to
0G Storage, which is public, unless you pass --allow-public.
- CI-safe. The action pushes the log before it anchors. It retries when
another push lands first, and it runs one job at a time. An anchor can
only ever cover entries that are on the branch.
SECURITY.md lists every attack the format catches, with the
test that proves each one, and the ones it does not catch.
docs/AUDIT.md covers the format, the CI setup, and branch
protection.
What it is not
- Germline doesn't make you compliant. It produces evidence for one
control, change management of AI behaviour. Your assessor decides the rest.
- It doesn't authenticate commit authors. Git lets anyone write any name.
The approval comes from GitHub's API and is authenticated; the author line
is only what git says. Signed entries are on the roadmap.
- It doesn't log inference traffic. LangSmith and Langfuse record what the
model said. Germline records what the model was configured to do, and
makes that record impossible to quietly rewrite.
How 0G is used
- 0G Chain holds the anchors.
GermlineAnchor is live on 0G mainnet at
0x18713A7ED60576C68B2CfE30D18839521a23cBcd
(contracts/GermlineAnchor.sol, about 85k gas per anchor). The CLI finds
it through deployments/zerog-anchor.json, so nobody needs to pass an
address.
- 0G Storage keeps an independent copy of each anchored log
(
lib/storage.js, via @0gfoundation/0g-storage-ts-sdk).
- 0G Compute reviews each change for the approver (
germline review, or
review: true in the action). A model on 0G Compute writes a two-sentence
summary and a risk level, which go into the log as a review entry bound to
the change by hash, with the model and request and response hashes. It
is advice, never an approval, and redacted values are never sent.
Other chains
The contracts are plain EVM (target paris), so the same scripts run on BOT
Chain (botchain.ai): --network bohr for its Bohr testnet (chain 968, faucet
at faucet.botchain.ai) or --network botchain for mainnet (chain 677). The
lineage registry has run its full lifecycle on Bohr; results and every
transaction are in docs/BOTCHAIN-TESTNET.md.
Status
| |
|---|
| Hash chain, per-commit tracking, CLI, GitHub Action, evidence pack, browser verifier | done, tested |
| Anchor registry contract | live on 0G mainnet, 0x18713A7E…cBcd |
| This repository's own log, anchored and verified | done: first anchor, verify --strict passes; evidence pack |
Agent config timelock (GermlineGuard) | live on 0G mainnet for this repo's log, 0x7eAAA03c…fA92; deploy one per agent |
| 0G Storage upload | code path done; first mainnet upload needs a funded key |
| Hosted anchoring (paid tier): GitHub OIDC or token per log, rate limit, receipt checked against the registry, public pins page | done, tested on a local chain; goes live once the service key is set in Vercel |
| Release tag | done: v0.4.0, so uses: let-the-dreamers-rise/[email protected] works |
| npm package | done: [email protected] |
Repository
bin/germline.js CLI: init, track, verify, anchor, report, id, demo
action.yml the GitHub Action
sdk/audit.js hash chain, diff, anchoring, chain verification
sdk/track.js per-commit tracking from git
sdk/report.js evidence pack (Markdown, JSON, CSV)
sdk/github.js pull-request approvals from the GitHub API
web/api/ hosted anchoring service (Vercel functions)
contracts/GermlineAnchor.sol append-only anchor registry
contracts/GermlineGuard.sol timelock on an agent's anchored config
web/verify.html browser verifier, no upload, no third-party code
docs/ AUDIT (format, CI), AGENTS, BUSINESS; SEARCH and SDK cover the legacy config search
test/ mocha (SDK, CLI) and hardhat (contracts) tests
MIT licensed.
