agent-hub docs

Install and run the hub

Install the container, a release binary, or from source, and run it

Guide#user#install#configDownload Markdown

By the end you will have the hub running and answering its health probes. This page is the one canonical install; Choose your setup tells you which lane is yours, and Deploy as a service turns a running hub into one that starts on boot.

Before you start

Thing Why
An admin token the control surface refuses every request without one
A place for the data a named volume, or a directory you control
Podman or Docker, or a Rust toolchain one of the install lanes below

Set the token once and keep it out of your shell history where you can:

HUB_ADMIN_TOKEN="$(openssl rand -hex 32)"

The container

Pull and run the published image. This is the default lane.

podman pull ghcr.io/abn/agent-hub:1.0.0
podman run --detach --name agent-hub \
  --publish 127.0.0.1:8080:8080 \
  --env HUB_ADMIN_TOKEN="$HUB_ADMIN_TOKEN" \
  --volume agent-hub-data:/data \
  ghcr.io/abn/agent-hub:1.0.0

docker run takes the same arguments. The image is distroless and runs as a non-root user, so it needs no shell. It publishes to loopback here; widen the bind in Network and access once you have a token and a plan for TLS.

To build the image from a checkout instead of pulling it, pass the commit in. The image context carries no .git, and the Settings Version row reads the version and that commit:

podman build -f Containerfile \
  --build-arg GIT_COMMIT="$(git rev-parse --short HEAD)" \
  --tag ghcr.io/abn/agent-hub:1.0.0 .

Compose builds that image, mounts a named volume at /data, keeps the rest of the filesystem read-only, sets a stop grace period above the hub's drain, and refuses to render without HUB_ADMIN_TOKEN:

HUB_ADMIN_TOKEN="$HUB_ADMIN_TOKEN" \
  docker compose -f deploy/compose.yaml up --detach

Stop the stack with docker compose -f deploy/compose.yaml down; the named volume keeps the data.

A release binary

Each GitHub release carries one archive per platform: Linux on x86_64 and arm64, statically linked, and macOS on Apple silicon and Intel. Windows is not built. The archive holds the full binary, server and client in one, with a .sha256 checksum beside it. Download the one for the host, check it, and unpack it:

VERSION=v1.2.0
TARGET=aarch64-apple-darwin
NAME="agent-hub-$VERSION-$TARGET"
BASE="https://github.com/abn/agent-hub/releases/download/agent-hub-$VERSION"
curl -fsSLO "$BASE/$NAME.tar.gz"
curl -fsSLO "$BASE/$NAME.sha256"
shasum -a 256 -c "$NAME.sha256"
tar -xzf "$NAME.tar.gz"
"./agent-hub-$VERSION-$TARGET/agent-hub" --help

TARGET is one of x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, aarch64-apple-darwin, or x86_64-apple-darwin.

From source

A stable Rust toolchain, 1.97 or newer. The pinned engine compiles C, so you also need a C toolchain with clang and cmake. make build produces a debug binary; for a release binary use the locked build:

cargo build --release --locked

Run the binary

Point the process at a data directory and a bind address:

HUB_DATA_DIR=./data HUB_BIND=127.0.0.1:8080 HUB_ADMIN_TOKEN=change-me \
  ./target/debug/agent-hub

On start it prints one line naming the bound address, the data directory, and whether an admin token is configured, so a port 0 bind is readable without turning on logs. RUST_LOG=info turns on the rest of the tracing output. The release binary lives at target/release/agent-hub.

Check it

From another shell:

curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz

/healthz answers ok while the process runs. /readyz asks the engine for its schema version and answers with it, or a 503 problem when the store does not reply. Point a container healthcheck at /readyz; the binary's own health --url http://127.0.0.1:8080 subcommand does exactly that and exits non-zero the moment the store stops answering.

Where the data lives

On first start the hub creates the data directory and its sessions/, kb/, and artifacts/ children, then opens hub.db at the top of the directory. hub.db holds the event store; the child directories hold the per-session brains, the project knowledge bases, and the artifact blobs. Back up the whole directory as one unit; Back up and restore has the procedure.

You should now see

A hub logging its bound address and answering /readyz with a version. Open http://127.0.0.1:8080/ and paste the admin token: Open the app and log in walks through it.

Note

A missing configuration file is not an error, and a file that others can read warns on stderr when it holds a token, and still works. Every setting, its default, and its environment variable is in Configuration.

See also