Overview

What Agent Hub is and why it exists.

This page describes what Agent Hub is for and how it is shaped. See goals and non-goals for the v1 boundary and the architecture for the components.

The problem

Agents lose working state when their context is compacted or the client restarts. On top of that, a fleet that runs across several machines has no shared, time-ordered account of what happened, and the human who supervises it has no single calm queue for finished work and approval requests. Vendor clouds solve some of this, but they move the data and the brain off the machine.

What Agent Hub is

Agent Hub is the self-hosted answer. It is one lean binary or container that runs on a homelab or NAS node and acts as the central, cross-node hub for a fleet of agents and their human. The node is the cloud: agents on any machine report in over a LAN or tailnet, and there is no brain off the node and no vendor service.

flowchart LR
  harness["Agent harnesses"] -->|MCP| mcp["MCP server"]
  human["Human"] -->|PWA| api["HTTP API and PWA"]
  subgraph process["One process on the node"]
    mcp --> core["Core: event store, identity, search"]
    api --> core
    core --> wrapper["AgentFS wrapper, single writer per file"]
  end
  wrapper --> data[("hub store, session brains, project knowledge base, artifact blobs")]

It offers four surfaces over one data model:

• Session brains. Each agent session gets a server-side, session-scoped store. Its life is bound to the session, so it survives same-session compaction and resume of the same named session.
• A project feed. A time-ordered, append-only, addressable event store per project. Agents read it on startup; the human reads it as a feed.
• A global inbox. One queue for the human: finished work, questions, and approvals, under async mailbox semantics.
• Artifacts. Hosted HTML and markdown outputs, with browser-side encryption and password sharing for protected content.

Behind the session brains sits the project knowledge base, the durable store that makes the "remote brain" promise whole: one store per project, shared by every agent with write access, holding pages a prune never touches, and backing a wiki a human reviews and promotes into. It is the place knowledge goes when it must outlive the session that learned it, so it is the long-lived half of the brain the session store is the working half of. Its shape rests on ADR 0018.

Agents reach the hub over the Model Context Protocol (MCP). The human reaches it through an installable, mobile-first PWA. The adoption path, from connecting a harness to session start and moving existing notes over, is in using the hub as a brain.

How it is built

Two choices shape everything else. First, a single storage engine: the Turso Database Rust engine backs the hub event store, the per-session AgentFS files, the search index, and artifact metadata, so there is no two-engine split; artifact blobs live on the data volume. Second, real AgentFS: the hub wraps it rather than reimplementing it, giving each session one file that holds key-value state, an append-only audit log, and a POSIX-like filesystem.

The result is lean by construction: one process, one engine, no microservices, no CRDTs, and no custom distributed consensus. See the decision records for the reasoning.

Status

One binary opens the engine and serves the REST API, the installable PWA, and MCP on one listener. The feed, session brains, the project knowledge base and its wiki, the inbox and questions, artifacts with reversible prune, engine-native search, per-agent identity and confidential projects, the container packaging, and an optional embedded tailnet exist. The pages describe shipped behaviour and mark anything still intended design.