Docs

How it works

The parts of an Acahti instance, where its data lives, and the optional modules.

Hosts

people ─┐
        ├─► your TLS proxy or tunnel ─► Acahti control plane ─► Runner
agents ─┘

Host	Runs
Control plane	The gateway image `ghcr.io/benchyard/acahti`, Forgejo, Woodpecker server, and PostgreSQL, in Docker Compose under `~/acahti`. No pipelines run here
Runner	One Woodpecker agent that executes jobs. Parallelism follows the host's CPU and memory

The gateway

The Go gateway is the only public application. The web app, MCP, and the REST API all call one internal catalog, so every surface sees the same data and the same permissions.

Path	Client	Backend
`/ui/*`	People in the browser	Catalog
`/mcp`	IDE agents	Catalog
`/acahti/v1`	CLI, scripts	Catalog
`/<org>/<repo>.git`	Git	Proxied to Forgejo as the authenticated user
`/api/packages/*`	npm, pip, uv	Proxied to Forgejo as the authenticated user
`/hooks/*`	Forgejo, Woodpecker	Index updates and live events

Lists, the Board, and navigation read from the gateway's own index in PostgreSQL, which kernel webhooks keep current. File contents, diffs, and step logs are read live from the kernels.

Pipelines

A push or pull request triggers Woodpecker. Before a job starts, the gateway expands its YAML: official pipes become acahti-pipe calls, named secrets become environment, and publishing pipes get the identity of the person who triggered the run. Results flow back through webhooks into the index, where checks_wait, the Inbox, and the Board read them. See Pipelines.

Data

All state is under ACAHTI_DATA as bind mounts. Once data exists, never run docker compose down -v.

Directory	Contents
`postgres/`	Databases for Forgejo, Woodpecker, and the gateway
`forgejo/`	Git repositories and Forgejo state
`woodpecker/`	Woodpecker server state
`gateway/`	Invites, OAuth clients, access tokens, module files

Back up PostgreSQL and ACAHTI_DATA before every upgrade.

Optional modules

ACAHTI_MODULES turns on extra product areas. All are off by default; a disabled module creates no tables, shows no tab, and its APIs answer 404.

Module	Adds	Data
`work`	Tickets, todos, and documents	`work_*` tables, `gateway/work/`
`argos`	A browser for Argos test runs; CI links runs to pipelines	`argos_*` tables, `gateway/argos/`; ingest with `ARGOS_TOKEN`
`chat`	Org chat with a dock in the web app	`chat_*` tables

Agents see enabled modules in whoami.modules.

For agents: how-it-works.md