agent-fox hub

A headless harness for spec-driven, multi-agent software development. The harness gives each unit of work an isolated workspace with its own branch, files, and agents, and coordinates those agents through a validated specification package rather than ad-hoc chat.

The design is inspired by Intent from Augment Code but diverges intentionally: headless instead of desktop, coordination rebuilt on a structured spec package that freezes on approval, and all grounding unified under a single Context abstraction.

Architecture

The project produces two binaries:

Binary	Purpose
af-hub	API server -- owns user identity, OAuth, workspaces, and access control
afc	CLI client -- authenticates with the hub and manages resources

Data is stored in an embedded SQLite database (pure Go, no CGo). Authentication supports three credential types: admin tokens, user API keys, and workspace-scoped tokens.

The af-hub binary also includes a built-in git smart HTTP server that exposes workspace repositories at /git//.git for clone, fetch, and push operations.

Getting Started

Prerequisites

• Go 1.26+
• A GitHub OAuth application (for user login)

Build

make build

This compiles both binaries into bin/.

Configure the server

Create a config.toml in the working directory (or pass --config <path>):

[server]
port = 8080

[database]
path = "./data/af-hub.db"

[logging]
level = "info"

[workspace]
path = "./data/workspaces"
workers = 2

[[oauth.providers]]
name = "github"
client_id = "your-github-client-id"
client_secret = "your-github-client-secret"

Start the server

bin/af-hub

On first boot the server generates an admin token and writes the plaintext to admin_token (next to the config file). Save this value and export it for subsequent starts:

export AF_HUB_ADMIN_TOKEN=$(cat admin_token)
bin/af-hub

Authenticate with the CLI

bin/afc login

This opens a browser for GitHub OAuth, exchanges the code, and saves credentials to ~/.af/config.toml. From here you can create workspaces, manage API keys, and issue workspace tokens.

Verify the server is running

curl http://localhost:8080/healthz
# {"status": "ok"}

curl http://localhost:8080/readyz
# {"status": "ready"}

Documentation

Document	Description
API Reference	REST API endpoints, authentication, request/response schemas
CLI Reference	afc commands, flags, and configuration
Server Configuration	config.toml reference and environment variables

Development

make check            # lint + tests
make test             # tests only
make lint             # go vet
make buildc           # build container image via podman
make hub-reset        # reset data and first-boot
make hub-run          # run the container
make clean            # remove bin/ and container image

The web UI scaffold (Vite + React + TypeScript) lives in web/:

make web-dev    # start dev server with API proxy
make web-build  # production build
make web-lint   # lint frontend

License

See LICENSE for details.