GitHub - Abraxas1010/agenthalo: Agent H.A.L.O. — Human-AI Agent Lifecycle Orchestrator. Tamper-proof observability for AI agents, backed by NucleusDB (verifiable database with SHA-256 Merkle proofs, ML-DSA-65 signatures, and Certificate Transparency).

_{Our tech stack is ontological: Hardware — Physics, Software — Mathematics}

Agent H.A.L.O. — Human-AI Agent Lifecycle Orchestrator
Sovereign identity, post-quantum communication, tamper-proof observability, and verifiable storage for AI agents.

Overview · Quick Start · Platform Components · NucleusDB · AgentPMT · P2PCLAW · Security · Formal Verification · Architecture

_{Part of the MENTAT stack — Layer 1 foundation.}

Overview

Agent H.A.L.O. is a sovereign agent platform. It gives AI agents a cryptographic identity, quantum-resistant communication, and tamper-proof observability — all running locally on your machine.

Identity. Each agent derives a DID (Decentralized Identifier) from a genesis seed ceremony. The DID document carries Ed25519, X25519, ML-KEM-768, and ML-DSA-65 public keys — classical and post-quantum cryptography side by side.

Observability. AgentHALO wraps AI coding agent CLIs (Claude Code, Codex, Gemini) and records every event — thoughts, tool calls, file edits, token counts, and costs — into a local NucleusDB trace store. Every trace event is content-addressed with a SHA-512 Merkle proof. If any event is modified after the fact, the proof chain breaks.

Communication. Agents exchange DIDComm v2 encrypted messages using a hybrid KEM (X25519 + ML-KEM-768) resistant to both classical and quantum adversaries. Messages route over a libp2p P2P mesh or through the Nym mixnet for network-layer anonymity.

Economics. Agents hold an EVM wallet (secp256k1, derived via BIP-32) for on-chain operations. EVM transaction signing is gated by DIDComm-verified dual-signature authorization (Ed25519 + ML-DSA-65), creating a two-cryptosystem barrier.

Key properties:

Zero telemetry. Nothing leaves your machine. No analytics, no tracking, no phone-home.
Zero config. agenthalo run claude auto-injects the right flags for structured output.
Tamper-evident. Content-addressed storage in NucleusDB with Merkle proofs (SHA-512).
Post-quantum. Hybrid KEM (X25519 + ML-KEM-768) for DIDComm, ML-DSA-65 for signatures, HKDF-SHA-512 for key derivation.
Sovereign identity. DID-based identity with dual classical/PQ key pairs, genesis seed ceremony, and append-only identity ledger.
Agent-native. Parses each agent's native structured output format.

Quick Start

One-Line Install

curl -fsSL https://raw.githubusercontent.com/Abraxas1010/agenthalo/master/install.sh | bash

Build from Source

git clone https://github.com/Abraxas1010/agenthalo.git
cd agenthalo
cargo build --release

This produces 7 binaries:

Binary	Purpose
`agenthalo`	Main CLI — wrap agents, manage identity, sign, attest, govern, mesh, ZK, dashboard
`agenthalo-mcp-server`	MCP server for the full AgentHALO tool surface
`nucleusdb`	NucleusDB CLI — database creation, SQL, export, MCP, dashboard
`nucleusdb-server`	Multi-tenant HTTP API for NucleusDB
`nucleusdb-mcp`	Standalone NucleusDB MCP server (stdio + HTTP)
`nucleusdb-tui`	Terminal UI for NucleusDB
`nucleusdb-discord`	Discord recorder and slash-command bot

First Run

# Wrap an AI agent with full observability
agenthalo run claude

# Or launch the dashboard
agenthalo dashboard --port 3100

Platform Components

Agent Wrapping and Observability

AgentHALO wraps Claude Code, Codex, and Gemini CLI, recording structured traces into NucleusDB:

agenthalo run claude          # wrap Claude Code
agenthalo run codex           # wrap Codex CLI
agenthalo run gemini          # wrap Gemini CLI
agenthalo traces              # list recorded sessions
agenthalo costs               # aggregate cost tracking
agenthalo export <session>    # export session data

Identity and Cryptography

agenthalo genesis             # genesis seed ceremony
agenthalo identity            # manage DID identity
agenthalo keygen              # generate Ed25519 + ML-DSA-65 + ML-KEM-768 keys
agenthalo sign <payload>      # dual classical/PQ signature
agenthalo vault               # encrypted provider-key storage
agenthalo crypto              # cryptographic operations

Attestation and Trust

agenthalo attest <session>    # create content-addressed attestation with ZK proof
agenthalo audit <contract>    # audit a smart contract
agenthalo trust               # query trust score
agenthalo vote                # governance voting
agenthalo governor            # governor policy management

Mesh Communication

agenthalo mesh                # P2P mesh operations (libp2p + hybrid KEM)
agenthalo comms               # DIDComm v2 encrypted messaging
agenthalo nym                 # Nym mixnet integration
agenthalo privacy             # privacy controller settings

On-Chain Operations

agenthalo wallet              # EVM wallet management (BIP-32 derived)
agenthalo onchain             # deploy/interact with on-chain contracts
agenthalo x402                # x402 payment protocol
agenthalo deploy              # deploy TrustVerifier contracts

Orchestration

agenthalo agents              # manage agent pool
agenthalo access              # pod access control and capabilities
agenthalo zk                  # ZK compute (RISC Zero guests: range proofs, set membership, secure aggregation)
agenthalo proof-gate          # formal verification gate status

Cockpit

The cockpit provides a browser-based terminal environment with WebSocket-backed PTY sessions, deploy management, and real-time session monitoring.

NucleusDB

NucleusDB is a verifiable database engine with three properties usually split across separate systems:

A mutable working database with SQL, typed values, blob storage, vector search, and multi-tenant HTTP access
A proof surface where queries come with cryptographic commitment proofs
An immutable append-only mode with monotone seal chaining for audit logs and permanent records

# Create and configure
nucleusdb create --db ./records.ndb --backend merkle
printf 'SET MODE APPEND_ONLY;\n' | nucleusdb sql --db ./records.ndb

# SQL interface
nucleusdb sql --db ./records.ndb

INSERT INTO data (key, value) VALUES ('temperature', 42);
COMMIT;
SELECT key, value FROM data WHERE key = 'temperature';
VERIFY 'temperature';

The MCP surface exposes 16 tools (core database + Discord) over stdio and streamable HTTP transports.

Full reference: Docs/ARCHITECTURE.md.

AgentPMT

AgentPMT is an MCP-native tool infrastructure platform providing budget-controlled access to 100+ third-party tools (Gmail, Stripe, Google Workspace, blockchain scanners, and more).

AgentHALO integrates AgentPMT as a tool proxy: wrapped agents discover and call AgentPMT tools through a unified MCP tools/list. Native AgentHALO tools appear as-is (attest, audit_contract, etc.), while AgentPMT tools appear with an agentpmt/ prefix (e.g., agentpmt/gmail_send, agentpmt/stripe_charge). Budget controls and credentials live on the AgentPMT side. AgentHALO records all tool calls in the trace for cost tracking and observability.

agenthalo addon agentpmt status    # check integration status
agenthalo addon agentpmt enable    # enable tool proxy

P2PCLAW

P2PCLAW is a decentralized publishing and verification network for research papers. Agents publish, validate, and retrieve papers through HMAC-authenticated API calls to the P2PCLAW gateway.

agenthalo addon p2pclaw status     # connection and swarm status
agenthalo addon p2pclaw publish    # publish a paper to the hive
agenthalo addon p2pclaw validate   # validate a paper
agenthalo addon p2pclaw search     # search the paper swarm

Features:

Tiered access (tier1/tier2) with HMAC-SHA256 request signing
Vault-first credential storage with insecure fallback for development
Swarm status monitoring (agent count, paper count, mempool depth)
Paper lifecycle: submit, validate, search, retrieve
Dashboard integration: embedded p2pclaw.com with HALO control panel (publish, validate, investigate, chat, navigate between dashboard/network map/papers/mempool/agents views)

Discord Bot

nucleusdb-discord records messages into an append-only NucleusDB instance and exposes verification/search slash commands.

export NUCLEUSDB_DISCORD_TOKEN=...
export NUCLEUSDB_DISCORD_DB_PATH=./discord_records.ndb
./target/release/nucleusdb-discord

Slash commands: /status, /verify, /search, /history, /export, /channels, /integrity.

The bot batches writes by message count or timeout. On startup it backfills channel history from the last recorded message, then resumes live recording. Edits and deletes are logged as new immutable facts.

Smart Contracts

Solidity contracts for on-chain trust verification:

TrustVerifier.sol — on-chain attestation verification
TrustVerifierMultiChain.sol — cross-chain attestation queries
Groth16VerifierAdapter.sol — ZK proof verification adapter
CrossChainAttestationQuery.sol — cross-chain attestation query surface

Deploy and test via Foundry (contracts/foundry.toml).

Dashboard

The web dashboard surfaces all platform layers:

Setup — guided onboarding, API key management, agent CLI configuration
AgentPMT — tool proxy status, credential management, budget controls
Overview — system status, genesis, identity, communication, memories
Sessions — trace explorer with cost tracking
Configuration — runtime settings, provider keys, addon toggles
Trust — trust scores and attestation verification
Proof Gate — formal verification gate status and certificate pipeline
NucleusDB — database operations, SQL queries, Merkle verification
Cockpit — PTY terminal sessions, agent launcher, deploy management
P2PCLAW — hybrid embedded view: full p2pclaw.com iframe with a side control panel for HALO-specific operations (publish, validate, configure, chat)
MCP Tools — browse and test the full MCP tool surface

All three agent CLIs (Claude Code, Codex, Gemini) auto-discover the HALO MCP server via global configs written on dashboard startup.

Formal Verification

AgentHALO bridges runtime operations to machine-checked Lean 4 proofs maintained in the Heyting repository. Three layers:

Provenance surfaces — five Rust modules export formal_provenance() linking 22 runtime operations to canonical Heyting theorem FQNs and 19 local Lean mirror paths
Proof gate — configs/proof_gate.json defines 14 theorem requirements across 6 tool surfaces, each bound to an exact declaration-line SHA-256, Heyting commit hash, and Ed25519 signature requirement
Certificate pipeline — .lean4export signed provenance attestations validated by src/verifier/ against statement hash, commit hash, and signature

Current status: enforced mode. Use AGENTHALO_PROOF_GATE_SKIP=1 only for explicit development escape-hatch sessions.

python3 scripts/check_theory_boundary.py               # verify approved math boundary
./scripts/validate_formal_provenance.sh                # namespace-aware FQN resolution
./scripts/generate_proof_certificates.sh               # generate + sign certificates
cargo run --bin nucleusdb -- verify-certificate <file>  # verify a certificate

Local Lean mirrors: lean/NucleusDB/ (self-contained).

Full details: Docs/FORMAL_VERIFICATION.md.

Security

Post-Quantum Cryptography

Surface	Classical	Post-Quantum	Combined
DIDComm authcrypt/anoncrypt	X25519 ECDH	ML-KEM-768 (FIPS 203)	Hybrid KEM
DIDComm mesh transport	X25519 ECDH	ML-KEM-768 (FIPS 203)	Hybrid KEM
Identity signatures	Ed25519	ML-DSA-65 (FIPS 204)	Dual-signed
KEM key derivation	—	HKDF-SHA-512	256-bit PQ security
Identity ledger hash chain	—	SHA-512	256-bit PQ collision
Attestation Merkle tree	—	SHA-512	256-bit PQ collision
EVM transaction signing	secp256k1 ECDSA	PQ-gated (Ed25519 + ML-DSA-65)	Two-cryptosystem barrier

Operational

SHA-256 content sealing for Discord message records
Certificate-transparency style roots for commit history
Witness signatures on commits
Append-only seal chaining via immutable.rs
AES-GCM encrypted local files for identity/genesis/vault state
Argon2-based password-derived master keys
Ed25519-signed formal provenance certificates (enforced by default)
ZK compute: RISC Zero guests for range proofs, set membership, secure aggregation, algorithm compliance
Native operator/subsidiary orchestration guidance: Docs/container_operator_security.md

Architecture

                        ┌──────────────┐
                        │  AI Agents   │
                        │ Claude/Codex │
                        │   /Gemini    │
                        └──────┬───────┘
                               │
                        ┌──────▼───────┐
                        │  agenthalo   │  CLI wrapper + orchestrator
                        │   (main)     │
                        └──────┬───────┘
               ┌───────────────┼───────────────┐
               │               │               │
        ┌──────▼──────┐ ┌─────▼──────┐ ┌──────▼──────┐
        │  Identity   │ │   Comms    │ │  Economics  │
        │ DID/Genesis │ │  DIDComm   │ │ EVM Wallet  │
        │ PQ Keygen   │ │ libp2p/Nym │ │ x402/Trust  │
        └──────┬──────┘ └─────┬──────┘ └──────┬──────┘
               │               │               │
        ┌──────▼───────────────▼───────────────▼──────┐
        │                 NucleusDB                    │
        │  Verifiable DB · SQL · Merkle · Append-only  │
        └──────┬──────────────┬───────────────┬───────┘
               │              │               │
        ┌──────▼──────┐ ┌────▼─────┐  ┌──────▼──────┐
        │  AgentPMT   │ │ P2PCLAW  │  │   Discord   │
        │ Tool Proxy  │ │ Research │  │  Recorder   │
        │ 100+ tools  │ │ Publish  │  │  Slash Cmds │
        └─────────────┘ └──────────┘  └─────────────┘
               │              │               │
        ┌──────▼──────────────▼───────────────▼───────┐
        │              Smart Contracts                 │
        │  TrustVerifier · Groth16 · CrossChain        │
        └──────┬──────────────────────────────────────┘
               │
        ┌──────▼──────┐
        │   Formal    │     Lean 4 proofs (Heyting)
        │ Verification│     22 provenance surfaces
        │  Proof Gate │     14 gated requirements
        └─────────────┘

Core module map:

src/halo/ — identity, attestation, trust, governance, crypto, DIDComm, mesh, PQ, EVM
src/halo/agentpmt.rs — AgentPMT tool proxy integration
src/halo/p2pclaw.rs — P2PCLAW publishing and verification client
src/orchestrator/ — agent pool, task graph, A2A bridge, container dispatch
src/cockpit/ — PTY manager, WebSocket bridge, deploy, sessions
src/swarm/ — content-addressed chunk engine (bitswap, manifests)
src/pod/ — access policies, capabilities, DID ACL bridge
src/comms/ — DIDComm sessions, encrypted envelopes
src/commitment/ — commitment scheme core
src/trust/ — composite CAB, on-chain trust
src/container/ — agent hookup, mesh coordination, launcher
src/pcn/ — payment channel network adapter
src/puf/ — physical unclonable function server
src/halo/zk_guests/ — RISC Zero ZK circuits
src/protocol.rs — commits, proofs, witness signatures, seal chaining
src/sql/ — parser and executor
src/persistence.rs — snapshots plus WAL
src/verifier/ — certificate parser, proof gate, Ed25519 verification
src/transparency/ / src/vc/ / src/sheaf/ — formal provenance surfaces
src/mcp/ — MCP tool surface
src/dashboard/ — web dashboard
src/discord/ — recorder, recovery, slash commands
contracts/ — Solidity contracts (TrustVerifier, Groth16, CrossChain)

Full module map: Docs/ARCHITECTURE.md. Platform reference: Docs/AGENTHALO.md.

Native Ops

./scripts/agenthalo-instances.sh list
./scripts/agenthalo-instances.sh start-dev       # review dashboard (isolated home)
./scripts/agenthalo-instances.sh start-discord   # persistent Discord recorder
./scripts/agenthalo-instances.sh stop-dev
./scripts/agenthalo-instances.sh stop-discord

Runtime state lives under ~/.agenthalo-runtimes/.

Testing

cargo test

Test suites cover: end-to-end flows, SQL, keymaps, persistence compatibility, CLI smoke, Discord recording, formal integration (provenance surfaces, gate config, certificates), dashboard, HALO integration, mesh simulation, P2PCLAW integration, PCN, PUF, governance falsifiability, VCS, memory recall, and theory boundary enforcement.

Repository Layout

src/ — Rust implementation (~98K lines)
src/halo/ — AgentHALO platform layer (identity, crypto, comms, governance, trust)
src/orchestrator/ — multi-agent orchestration and A2A
src/cockpit/ — browser-based PTY and deploy management
contracts/ — Solidity smart contracts
dashboard/ — embedded frontend assets
deploy/ — systemd units and environment templates
configs/ — proof gate configuration
lean/ — Lean 4 mirror modules (NucleusDB provenance)
python/ — Python utilities
scripts/ — provenance validation, certificate generation, instance management
tests/ — integration and regression tests (19 test files)
wdk-sidecar/ — WDK sidecar service
artifacts/ — trusted setup artifacts

License

Released under the Apoth3osis License Stack v1. See LICENSE.md and licenses/.

Citation

See CITATION.cff.

Name		Name	Last commit message	Last commit date
Latest commit History 474 Commits
.agents		.agents
.claude/skills		.claude/skills
.codex		.codex
.gemini		.gemini
.github		.github
Docs		Docs
artifacts		artifacts
assets		assets
configs		configs
contracts		contracts
dashboard		dashboard
deploy		deploy
lean-xray		lean-xray
lean		lean
licenses		licenses
scripts		scripts
src		src
tests		tests
vendor/cipher-0.5.1-patched		vendor/cipher-0.5.1-patched
wdk-sidecar		wdk-sidecar
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
CODEX.md		CODEX.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
GEMINI.md		GEMINI.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh
lake-manifest.json		lake-manifest.json
lakefile.lean		lakefile.lean
lean-toolchain		lean-toolchain

Folders and files

Latest commit

History

Repository files navigation

Overview

Quick Start

One-Line Install

Build from Source

First Run

Platform Components

Agent Wrapping and Observability

Identity and Cryptography

Attestation and Trust

Mesh Communication

On-Chain Operations

Orchestration

Cockpit

NucleusDB

AgentPMT

P2PCLAW

Discord Bot

Smart Contracts

Dashboard

Formal Verification

Security

Post-Quantum Cryptography

Operational

Architecture

Native Ops

Testing

Repository Layout

License

Citation

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages