README
¶
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.
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"
[log]
level = "info"
[[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 build-container # build af-hub image via containers/hub/Containerfile
make run-container # run image with bin/ mounted for /config and /data
make clean # remove bin/
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.
Directories