Hearth
The central fire that keeps the forge running. Hearth is the orchestrator for every 
KATFORGE project: it manages secrets, runs the dev compose stack, deploys to Kubernetes, and clones every sibling repo.
One install command, then everything is hearth <command>.
Everything KATforge lives at ~/.katforge/. Nothing scattered across ~/.local/bin, ~/.config/sops, or system-wide package managers.
Why Hearth
A multi-repo studio with shared infrastructure has a coordination problem: every contributor has to install the same tools, clone the same repos, find the same secrets, and run the same dev stack the same way. Without a single entry point, that knowledge lives in heads and stale wikis.
Hearth makes the orchestrator the source of truth.
- One root.
~/.katforge/holds every repo, every binary, every secret key. - One install. A single bash script clones hearth and bootstraps everything else.
- One CLI.
hearth up,hearth ship,hearth secret,hearth team. No project-specific tooling to memorize. - One key. Your age private key authorizes you for sops-encrypted secrets across every service.
What it does
| Task | Command |
|---|---|
| Start the local dev stack | hearth up |
| Run a frontend in dev mode | hearth dev katforge |
| Show every dev URL | hearth urls |
| Deploy a service to prod | hearth ship api |
| Roll back a deployment | hearth rollback api |
| Edit an encrypted secret | hearth secret edit dev api |
| Authorize a teammate | hearth team add age1abc... |
| Diagnose your install | hearth setup |
See the commands reference for the full surface.
What's next
- Install — one-shot bootstrap from a clean machine
- Filesystem layout — what lives where under
~/.katforge/ - Commands — the full CLI surface
- Environments —
dev,test,qa,prod - Secrets — sops + age, team membership, key rotation
- Deployment — production architecture (cluster, DNS, db)
- Shipping — the ship pipeline end to end
- Troubleshooting — when things go sideways