Overalls.

An AI-first developer platform that you own.

 Guide Self-host
Design Architecture
Source GitHub · MIT Appearance

Self-host Overalls

Overalls runs on hardware you control and nowhere else. This guide covers going from a bare-metal server to signing in and starting your first machine. It's a summary: each page links to the full operator documentation in the repository, which is the source of truth.

Audience
Operators who are comfortable with NixOS, SSH and PostgreSQL
Time
An afternoon for one host, if your DNS and email relay are ready

What you're building

  • Marshall: the web app and control plane, behind HAProxy with ACME certificates, using PostgreSQL and an SMTP relay.
  • Lilly on every host: runs Firecracker guests on a ZFS pool.
  • Porsche: the SSH management gateway. Audi: DNS, guest SSH and public web apps.
  • Optional edge services: Brady (egress cache), Enrico (GitHub mirror), Ziggy (inference) and Galileo (integrations).

Every role can run on one host. A deployment with redundancy spreads Marshall across at least three hosts with a highly available database.

Your fleet is a Git repository

Each host polls the trunk branch of a Git repository you control, builds its own Buck2 deployment target, applies migrations, switches and checks its own health. So step one is to fork Overalls and make the fleet yours:

  1. Fork github.com/ghuntley/overalls to a Git server your hosts can reach over SSH.
  2. Replace the example hosts in fleet/hosts/ with your own. The fleet/roles/control-plane/ modules and fleet/hosts/panterloons/ show the control-plane configuration; fleet/hosts/dungarees/ is a worker.
  3. Put operators and recovery users in nix/policy/identity/users.nix. Declare host roles in nix/policy/fleet/ and reviewed network sources in nix/policy/network/allowed-hosts.nix. Public addresses live in the encrypted fleet-addresses document, with logical names in nix/policy/network/fleet-addresses.nix.
  4. Commit and push to trunk. Encrypted secrets live under secrets/; plaintext never goes in the repo.

Buck2 is the build entry point. Nix supplies the pinned toolchains and dependencies and assembles the NixOS systems and guest images.

Requirements

Hosts
x86_64 bare metal with a working /dev/kvm. The bootstrap tool knows Hetzner dedicated and EC2 bare metal. The target needs root (or passwordless sudo), Python 3, OpenSSH, lsblk and iproute2.
Disks
Two system disks on Hetzner, or the root EBS volume on EC2. Guest disks live on native ZFS.
Database
PostgreSQL, reached over verified TLS
Email
An SMTP relay with authentication and verified TLS (implicit TLS or STARTTLS), for magic-link sign-in
DNS
A domain you control. The apex points at your Marshall hosts and apps.<your-domain> is delegated to Audi. See Set up DNS.
Laptop
Nix with flakes, a checkout of your fork, and an Ed25519 operator SSH key

The path

  1. Overview and requirements (this page)
  2. Provision a host: discover, review, plan, install, enroll
  3. Deploy the control plane: modules, secrets, database, email, TLS
  4. Set up DNS: apex records and the Audi delegation
  5. Enroll hosts and images: Lilly credentials, guest images, Porsche
  6. Your first machine: sign in, SSH keys, CLI, terminal
  7. Day-two operations: updates, drains, backups, logs

Full reference: docs/operations/deployment.md