Machine Genome is an open identity and provenance protocol for models, agents, harnesses, datasets, and the artifacts that connect them. Every immutable, signed genesis record receives a content-addressed Gene. Genes form a verifiable lineage graph; later amendments and third-party attestations add evidence without rewriting history.

Live registry: machinegenome.org · Protocol: MGS 0.1.1 implementation profile · API: OpenAPI 3.1

Modern agents are assembled from model weights, prompts, scaffolds, tools, datasets, and runtime policy. Names alone cannot answer which exact components were used, who asserted the relationship, or whether the evidence changed. Machine Genome provides:

• stable identity — a Gene is a SHA-256 multihash of a secured canonical genesis record;
• explicit lineage — typed parent edges distinguish authorized, operator-observed, and unresolved relationships;
• cryptographic accountability — W3C eddsa-jcs-2022 proofs bind records to controller DIDs;
• append-only evolution — ordered amendments and independent attestations add history without mutating genesis;
• public transparency — registries provide canonical bytes, inclusion and consistency proofs, signed checkpoints, conflict evidence, and tombstones.

The implementation has no dependency on a blockchain, a specific model vendor, Prometheus, Matrix, or a proprietary DID resolver. The current profile resolves Ed25519 did:key identities offline.

See project status for the precise implemented, validated, and deferred boundaries.

Requirements: Go 1.24 or newer, GNU Make, and jq.

git clone https://github.com/paxlabs-inc/machine-genome.git
cd machine-genome
make check build

bin/mgs keygen --out controller.key.json
bin/mgs init-genesis \
  --key controller.key.json \
  --name cody \
  --namespace example.org \
  --subject-type agent \
  --version 1.0.0 \
  --out genesis.unsigned.json
bin/mgs sign \
  --in genesis.unsigned.json \
  --key controller.key.json \
  --out genesis.json
bin/mgs verify --in genesis.json
bin/mgs gene --in genesis.json

Private key files are created with mode 0600. Never commit keys, registry tokens, or private evidence.

bin/mgs keygen --out registry-checkpoint.key.json
umask 077
openssl rand -hex 32 > admin.token

bin/mgs registry-serve \
  --data-dir ./registry-data \
  --checkpoint-key registry-checkpoint.key.json \
  --admin-token-file admin.token \
  --listen 127.0.0.1:8080 \
  --public-base-url http://127.0.0.1:8080

Open http://127.0.0.1:8080. DNS namespaces must complete the registry's dns-01 controller challenge before their first genesis is admitted. DID namespaces are accepted when the namespace equals the signing controller DID. --allow-unverified-namespaces is for isolated development only.

For a production deployment, follow the operations runbook and deployment asset guide.

authoring CLI / library
        │ secured MGS records
        ▼
  verification boundary ── strict JSON + JCS + DID + signature + lineage
        │ admitted canonical bytes
        ▼
 ACID object store ── indexes ── append-only Merkle log ── signed checkpoint
        │                         │
        ├── HTTP API              └── inclusion / consistency proofs
        └── provenance explorer

The shared admission boundary is registry.Store.Submit; the HTTP service cannot bypass record verification. Read the full architecture and threat model before extending trust or resolver behavior.

• Documentation index
• Concepts and trust semantics
• Protocol implementation profile
• Protocol audit
• Registry HTTP API and OpenAPI
• CLI reference
• Architecture
• Threat model
• Conformance and test vectors
• Production operations
• Public registry policy
• Versioning and compatibility
• Governance, security, and contributing
• Roadmap

make help
make check       # tests, vet, schemas, API contract, docs, records
make race        # race detector
make coverage    # HTML and textual coverage report
make build       # static local binary
make dist        # release archives and checksums

CI repeats the conformance, race, build, record, repository, and vulnerability scans on every change. Tagged releases are built from a clean tree with checksums and a software bill of materials.

Do not report security vulnerabilities in a public issue. Follow SECURITY.md to use GitHub's private vulnerability reporting. Cryptographic review, privacy review, independent witnesses, checkpoint gossip, federation, and neutral standards governance remain explicit roadmap work.

The Go implementation and repository tooling are licensed under Apache-2.0. Protocol and explanatory documentation are made available under CC BY 4.0. Signed registry records do not grant rights in the external models, source repositories, datasets, or artifacts they reference. See NOTICE for provenance and attribution.