README.md

Agentbox documentation

Audience-tiered navigation. Pick the path that matches what you are trying to do — then follow the cross-links. Every doc here is a relative hop from this index.

flowchart LR
    subgraph docs["docs/"]
        U["user/<br/>You run agentbox"]
        D["developer/<br/>You change agentbox"]
        I["integration/<br/>External service wiring"]
        R["reference/<br/>Canonical specs:<br/>ADR / PRD / DDD"]
    end
    U -->|"first boot"| QS["user/quickstart.md"]
    U -->|"sovereign stack"| SS["user/sovereign-stack.md"]
    D -->|"how it fits"| AR["developer/architecture.md"]
    D -->|"adapter slots"| AD["developer/adapters.md"]
    R -->|"decisions"| ADR["reference/adr/"]
    R -->|"requirements"| PRD["reference/prd/"]
    R -->|"domains"| DDD["reference/ddd/"]

Loading

Agentbox is a sovereign, manifest-driven headless agent runtime: 113 skills, an 18-kind URN namespace, five pluggable adapter slots, and an embedded did:nostr / solid-pod / Nostr-relay substrate. The reference shelf below is the authoritative record — 35 ADRs, 17 PRDs, 15 DDDs, 2 QE reviews.

---

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)
agentbox.sh CLI reference	The operator entrypoint — local stack management and remote OCI commands
Setup dashboard	Browser-based SPA for editing agentbox.toml and observing the running container (ADR-024)
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 — the DreamLab-AI ecosystem substrate
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
Native pod tunnel	Publish the in-container pod at pods-native.dreamlab-ai.com via the cloudflared compose overlay (origin http://agentbox:8484)
Nostr relay	External-agent messaging over the embedded Nostr relay with pod-inbox bridge — including the Agent Control Surface Protocol (kinds 31400-31405) for cross-repo governance with the forum and the host project's broker actor
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

Federation & multi-tenant
Mesh deployment	Standalone / client / mesh federation modes over the embedded Nostr relay
Multi-user did:nostr pods	Per-tenant did:nostr identity and pod allocation — design surface and deployment shapes (ADR-017 / PRD-007; scaffolded, default off)
Git-versioned pods	[sovereign_mesh.git] initialises each pod directory as a git repository at provisioning time
Tailscale	WireGuard mesh networking so instances federate across a tailnet without static IPs or firewall holes

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
Native pod mesh	In-container git-versioned solid-pod-rs tier — architecture + wiring (PRD-007 / ADR-010)
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 multi-substrate DreamLab federation mesh
Skills upgrade path	Migrating from path:./skills to a standalone repo

Subsystems & deep-dives
Code-as-harness	Persistent Python kernel MCP, ExpeL lesson distillation, Voyager skill library (PRD-008)
Code-harness multi-tier memory	How kernel state, distilled lessons, and verified skills layer over RuVector
Economy loop	End-to-end cross-repo demo — an agent pays for a cost-gated pod read, settles via the 402 consumer pipeline, emits URN receipts (PRD-015)
Agent control surface panels	ACSP panel schema — emit valid Nostr events (kinds 31400-31405) that render governance control panels

Diagrams — cartographic audits
Adapter dispatch sequence	Source-grounded sequence + flow diagrams of the five-slot adapter dispatch pipeline
Identity & agent comms	Source-referenced diagrams of did:nostr plumbing, session mirror, and relay flows

Tooling & governance
Testing	Suite shape, running locally, CI wiring
Version tracking	Renovate + nix flake update workflow
Licensing	AGPL-3.0 component matrix and aggregation analysis for every bundled copyleft component

---

Integration — external service wiring

Service
ComfyUI integration	Historical patch artifacts for wiring an external ComfyUI backend — the integration is already applied in management-api/server.js

---

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	Host-project 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 (partial)	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; gated by [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; 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 challenge & scheme-detection grammar	Accepted	Pure-function 402 classifier (agentbox-ledger/x402/l402/unknown), frozen byte-fixture corpus, additive accepts[] emission, Lightning-first settlement — companion to PRD-015
ADR-033	did:nostr Multikey convergence	Accepted	Single canonical DID Document form; supersedes ADR-074 D2 verificationMethod shape, retains D1
ADR-034	Headroom Rust crate integration	Proposed	Content-aware context compression via N-API; companion to PRD-016
ADR-035	Project-tracking telemetry & kind-30841	Accepted	Port-bound agentbox_project_* metrics + addressable kind-30841 digest; no new URN kind, port, or adapter slot

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 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	Host-project 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 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-016	Context compression & caching	Headroom hybrid Rust+Python compression integration; companion to ADR-034 and DDD-014 (Draft)
PRD-017	Sovereign project tracking	Helm-grade project tracking re-expressed on the three sovereign substrates — no new kind, port, or adapter slot (Draft)
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 gates (Proposed)
DDD-013	Hardening boundary domain	NetworkEdgePolicy + PrivilegeModel + SecretMaterialisation + DefenceInDepthLayer aggregates
DDD-014	Compression & cache domain	Context-compression bounded context; middleware ordering after the JSON-LD encoder (Proposed)
DDD-015	Project-tracking domain	TrackedProject + ProjectScan + CommitWindow + ProjectPrimer + TrackingDigest; rides memory + events slots

QE reviews

#	Document	Title	Status
QE-001	Code-as-harness traceability review	PRD-008 / ADR-018 / ADR-019 / DDD-005 traceability review	Complete
QE-002	Code-as-harness 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, naming conventions used across all reference documents
reference/_vocab/agentbox-v1.context.jsonld	The pinned agbx: JSON-LD context document — the machine-readable counterpart to agbx.md

---

Reading order

New operators

1. user/glossary.md — orientation vocabulary
2. user/quickstart.md — build and run
3. user/sovereign-stack.md — identity → pod → relay → privacy-filter, end to end
4. user/configuration.md — the agentbox.toml manifest

New contributors

1. ../README.md — product pitch + top-level architecture
2. developer/architecture.md — how it works inside
3. reference/prd/PRD-001-capabilities-and-adapters.md — the full product spec
4. reference/adr/ADR-005-pluggable-adapter-architecture.md — adapter deep-dive
5. The other ADRs in order — they explain how the design got here

Conventions

• Mermaid for diagrams. Diagrams are Mermaid blocks. The few binary images in this tree are deliberate exceptions: the project banner (agentbox.png) and the two setup-dashboard screenshots under images/ (setup-dashboard.png, setup-wizard-overview.png).
• 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.
• Status tags. ADRs carry status: frontmatter; PRDs carry a version/status 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.
• Host-by-role. Agentbox is standalone (github.com/DreamLab-AI/agentbox). The integrating host is referenced by role — "host project", "integrator", "external orchestrator" — never by name. Host-specific integration lives in the host's own docs.
• UK English. All documentation uses British spelling (organisation, colour, initialise, behaviour, centre, analyse).