README.md

Agentbox documentation

Audience-tiered navigation. Pick the path that matches what you are trying to do.

graph LR
    subgraph docs["docs/"]
        U["user/<br/>You run agentbox;<br/>you want it to work"]
        D["developer/<br/>You change agentbox;<br/>you ship PRs"]
        R["reference/<br/>Canonical specs<br/>ADR / PRD / DDD"]
    end
    U -.->|quickstart| QS[user/quickstart.md]
    U -.->|config| CF[user/configuration.md]
    D -.->|architecture| AR[developer/architecture.md]
    D -.->|adapters| AD[developer/adapters.md]
    R -.->|ADRs| ADR[reference/adr/]
    R -.->|PRDs| PRD[reference/prd/]

Loading

---

User docs — for operators

You have a machine, you want agentbox running on it, ideally with as little fuss as possible.

Start here
Glossary & orientation	Zero-to-one for people new to headless agent runtimes
Quickstart	First boot in ten minutes
Installation	Per-OS install paths (Linux, macOS, Windows, remote)
Configuration	agentbox.toml reference — every section, every key
Running	Copy-paste recipes per host × arch × GPU
Platforms	Compatibility matrix: what works where
Troubleshooting	Common failure modes and fixes

Day-2 operations
Providers	API-key management — [providers.*] manifest sections
Backup & restore	agentbox.sh backup / restore — what's included, secrets handling
Consuming the image	GHCR registry tags, multi-arch manifest
Provisioning remote hosts	agentbox.sh provision --target oci | fly | hetzner | bare

Sovereign data stack — key parts of the DreamLab-AI ecosystem
Sovereign stack — end to end	Start here. One-page walkthrough of identity → pod → relay → privacy-filter with verifiable commands
Solid pod (solid-pod-rs)	First-party Rust Solid Protocol 0.11 server — durable storage, WAC 2.0, did:nostr, atomic-rename, quota, rate-limit
Nostr relay	External-agent messaging over an embedded Nostr relay with pod-inbox bridge — including the Agent Control Surface Protocol (kinds 31400-31405) for cross-repo governance with the forum (nostr-bbs-core governance module) and VisionClaw's BrokerActor
Mobile bridge	Talk to your agents from a stock Android Nostr client (Amethyst + Amber) — encrypted NIP-17 chat, NIP-26 phone delegation, and kind-30840 session summaries dual-written to your Solid pod. No bespoke app; the agent's key never leaves the container
Privacy filter	Local PII redaction sidecar (openai/privacy-filter) as adapter middleware
Linked-Data interfaces	Eleven JSON-LD federation surfaces — pods / Nostr envelopes / VCs / DID Docs / PROV-O / WoT / skills / payments / DCAT / arch-docs / HTTP meta
Canonical URIs	The URI grammar that names every emitted resource — did:nostr:<pubkey> + urn:agentbox:<kind>:[<scope>:]<local>, content-addressed, unconditionally unique, best-effort resolvable
JSON-LD browser	The S12 viewer slot — every emitted document one URL away, pane-dispatched by @type, follows URIs through /v1/uri/<urn>
Consultants — meta-router	Five MCP servers exposing Codex / Antigravity / Z.AI / Perplexity / DeepSeek as labelled consultants the coordinator can invoke explicitly

Feature guides
3DGS (COLMAP + METIS + LichtFeld)	3D Gaussian Splatting pipeline
Blender	Blender toolchain
ComfyUI	Built-in vs external ComfyUI
LaTeX	TeX Live full

---

Developer docs — for contributors

You are adding a feature, implementing an adapter, or investigating a regression.

Architecture
Architecture overview	How it all fits together — manifest → flake → image → runtime
Identity and tracing mesh	secp256k1 identity root, 18-kind URN namespace, adapter dispatch pipeline, credential provenance, federation invariants
Adapter pattern	Five slots × three classes; how to write a new impl
Sovereign mesh	Nostr client + NIP-98 auth + relay pool internals
Linked-Data middleware	Encoder + ContextResolver + LION linter + JCS — surface authoring guide
Ecosystem integration	Agentbox's role in the five-substrate DreamLab federation mesh
Skills upgrade path	Migrating from path:./skills to a standalone repo

Tooling
Testing	Suite shape, running locally, CI wiring
Version tracking	Renovate + nix flake update workflow

---

Reference — canonical specs

These are the authoritative sources of truth. Anything in user/ or developer/ that conflicts with these is a bug in the docs.

Architecture decisions (ADR)

#	Document	Status	Decision
ADR-001	Nix flake build	Accepted	Manifest-driven Nix flake replaces the monolithic Dockerfile
ADR-002	RuVector as embedded retrieval	Accepted	Local retrieval cache, not a source of truth
ADR-003	Guidance control plane	Accepted	Enforcement gates for autonomous agents
ADR-004	Upstream sync boundaries	Accepted	Selective sync, not mechanical
ADR-005	Pluggable adapter architecture	Accepted	Five-slot adapters × three impl classes
ADR-006	Immutable runtime bootstrap	Accepted	No dependency resolution at startup
ADR-007	Runtime contract + hardening	Accepted	Image ref + probes + observability + hardening as one contract
ADR-008	Privacy filter routing	Accepted	Local openai/privacy-filter sidecar as cross-cutting adapter middleware
ADR-009	Embedded Nostr relay	Accepted	nostr-rs-relay + pod-inbox bridge for external-agent messaging
ADR-010	solid-pod-rs as first-class pod server	Accepted	First-party Rust Solid Protocol 0.11 server; default pods implementation
ADR-011	Consultation MCP servers	Accepted	Coordinator + named-consultant pattern; rejects transparent API rewriting as the meta-router
ADR-012	JSON-LD 1.1 as the federation interchange grammar	Accepted	JSON-LD as the third cross-cutting middleware after observability and privacy; LION subset for hand-authored docs
ADR-013	Canonical URI grammar and resolver	Accepted	did:nostr:<pubkey> + urn:agentbox:<kind>:[<scope>:]<local>; uniqueness unconditional, resolvability best-effort; /v1/uri/<urn> resolver
ADR-014	Bi-directional graph-state ingress	Accepted	Bi-directional graph-state ingress for agent reaction
ADR-015	MCP ruvector-postgres mandate	Accepted	ruvector-mcp.cjs fails closed if PostgreSQL is unreachable; no silent sql.js fallback
ADR-016	License consolidation	Accepted	AGPL-3.0-only end-to-end; aggregation analysis for all third-party components
ADR-017	Multi-tenant did:nostr pods	Proposed	Per-tenant did:nostr identity; pod-per-tenant allocation and NIP-98 scoping
ADR-018	Persistent code-interpreter MCP	Accepted	Long-lived kernel sessions + CodeAct skill; execution-trace URN emission
ADR-019	Experiential skill learning	Accepted	Distilled lessons and verified skill library from execution traces
ADR-020	ACI MCP tree-search	Proposed	ACI MCP and execution-gated tree-search for agent capability improvement
ADR-021	LLM resource marketplace kinds	Accepted	Nostr kind schema for LLM resource listings, bids, and receipts
ADR-022	Runtime integrity hardening	Accepted	Immutable image digests, SBOM attestation, and supply-chain verification
ADR-023	Ontology bridge	Proposed	VisionClaw ontology bridge via MCP; BC20 anti-corruption layer
ADR-024	Setup dashboard architecture	Accepted	Setup wizard and operations dashboard — browser-based, zero-dependency
ADR-025	Multi-Harness tmux Architecture	Accepted	Multi-harness tmux layout for parallel agent workstreams
ADR-026	Cross-Substrate Agent-Loop Seams	Accepted (partially realised)	The five seams across the substrate mesh; BC20 ingest converges on the /wss/agent-events WS contract and retires :9500
ADR-027	Default-secure posture and runtime-isolation roadmap	Accepted	Loopback-publish + auth-default-on, supplemental seccomp denylist, no runtime sudo, secret-via-tmpfs; gVisor/WASI proposed
ADR-028	Per-User Agent Fabric	Accepted	Pod-sourced identity, RuVector memory, and heartbeat autonomy for per-user agents; gate aligned to [sovereign_mesh].per_user_agents
ADR-029	Session-mirror live egress	Accepted	Per-turn NIP-59 gift-wrapped self-DM under a derived child key; the live sibling of the kind-30840 digest, no external LLM hop, fail-open
ADR-030	Sovereign-mesh manifest boundary	Accepted	[sovereign_mesh] as one subsystem gate (default off; env override per R7); the one external data hop is the mobile-bridge Z.AI summarisation
ADR-031	Adapter contract enforcement	Accepted	The merge gate is executable: isReal:false banned, stateful loopbacks for federated legs, registered time-boxed exemptions, middleware-bypass coverage
ADR-032	402 payment challenge & scheme-detection grammar	Accepted	Pure-function 402 classifier (agentbox-ledger/x402/l402/unknown), frozen byte-fixture corpus, additive accepts[] emission, Lightning-first settlement (no native EVM rail) — companion to PRD-015

Product requirements (PRD)

#	Document	Summary
PRD-001	Capabilities and adapters	Agentbox as a standalone product
PRD-002	Immutable runtime bootstrap	Remove mutable dep-install from startup
PRD-003	Runtime contract + container hardening	Image selection + probes + observability + hardening
PRD-004	External agent messaging	Sovereign relay surface + pod-inbox bridge
PRD-005	Meta-router and consultant tier	Five consultant MCPs + manual /consult + automatic auto-consultant subagent
PRD-006	Linked-data interfaces and JSON-LD compatible surfaces	Eleven federation surfaces, pinned context catalogue, LION authoring subset
PRD-007	Multi-tenant federation	Per-tenant did:nostr identity, pod allocation, and NIP-98 scoping at scale
PRD-008	Code-as-harness integration	Persistent kernel sessions, CodeAct skill, execution traces, and skill library
PRD-009	LLM resource marketplace	Nostr-native marketplace for LLM compute listings, bids, and payments
PRD-010	Runtime integrity hardening	Immutable image digests, SBOM attestation, and supply-chain policy gates
PRD-011	Ontology bridge	VisionClaw ontology bridge exposing knowledge-graph concepts via MCP
PRD-012	Setup wizard and operations dashboard	Browser-based first-boot wizard and day-2 ops dashboard
PRD-013	Multi-harness tmux architecture	Multi-harness tmux layout and documentation revamp
PRD-014	Embodied agent loop	Voice-to-ontology gap closure across the five-substrate seams (In progress)
PRD-015	Consumer & broadcast economy surfaces	Phase 1 shipped — Outbound 402 payment consumer (detect → policy → pay → receipt) and service discovery broadcast (well-known manifest, standards-shaped challenges)
PRD-REMEDIATION-001	Default-secure posture remediation	Second-pass hardening: loopback publish, auth-default-on, zai allowlist, no runtime escalation, secret-via-tmpfs, doc truth-up

Domain design (DDD)

#	Document	Focus
DDD-001	Immutable bootstrap domain	RuntimeClosure aggregate + BootstrapPolicy
DDD-002	Runtime contract domain	ImageReferencePolicy + ProbeContract + ObservabilityBinding + SecurityProfile
DDD-003	Sovereign messaging domain	AgentIdentity + PodMailbox + RelayEndpoint + inbound/outbound envelopes
DDD-004	Linked-data interchange domain	ContextCatalogue + FederationSurface + EncodingPipeline + LinkedResource + LIONDocument
DDD-005	Code execution domain	KernelSession + ExecutionTrace + DistilledLesson + VerifiedSkill aggregates
DDD-006	LLM marketplace domain	Listing + Bid + Settlement + ProviderProfile aggregates; Nostr kind mappings
DDD-007	Runtime integrity domain	ImagePolicy + SBOMAttestation + SupplyChainVerifier aggregates
DDD-008	Ontology bridge domain	OntologyMapping + ConceptResolver + BC20 anti-corruption layer
DDD-009	Setup dashboard domain	WizardSession + ConfigBlob + HealthSnapshot + OperationsDashboard
DDD-010	Multi-Harness Coordination Domain	HarnessSession + WorkstreamRouter + TmuxLayout aggregates
DDD-011	Multi-Tenant Federation Domain	FederationPeer + MeshTopology + TenantIsolation aggregates
DDD-012	Sovereign Knowledge Elevation Domain	BC22 — personal-KG → governed-ontology elevation; mandate model + dual consistency/policy gates (Proposed)
DDD-013	Hardening Boundary Domain	NetworkEdgePolicy + PrivilegeModel + SecretMaterialisation + DefenceInDepthLayer aggregates

QE Reviews

#	Document	Title	Status
QE-001	PRD-008 / ADR-018 / ADR-019 / DDD-005 traceability review	Code-as-harness traceability review	Complete
QE-002	QE-001 defect re-verification	Re-verification of QE-001 defects on PRD-008 / ADR-018–020 / DDD-005	Complete

Vocabulary

File	Contents
reference/_vocab/agbx.md	Canonical agentbox term definitions — abbreviations, domain vocabulary, and naming conventions used across all reference documents

---

Reading order for new contributors

1. ../README.md — 5 minutes, product pitch + architecture
2. user/quickstart.md — build and run
3. developer/architecture.md — how it works inside
4. reference/prd/PRD-001-capabilities-and-adapters.md — full product spec
5. reference/adr/ADR-005-pluggable-adapter-architecture.md — adapter deep-dive
6. The other ADRs in order — they explain how we got here

Conventions

• Plain markdown. No binary images in docs. Diagrams are Mermaid blocks.
• Relative cross-refs. Every link is a relative path so the docs tree is portable.
• File size limit. Docs stay under 500 lines; heavier material lives in siblings (REFERENCE.md, EXAMPLES.md).
• Status tags. ADRs carry Status: at the top; PRDs carry a version block.
• Audience tiers are strict. user/ never references internal-only tooling; developer/ never re-explains operator basics; reference/ never loses a canonical claim to narrative drift.
• UK English. All documentation uses British spelling (organisation, colour, initialise, behaviour, centre, analyse, etc.).