Overalls. An AI-first developer platform that you own.	Guide	Self-host
Design	Architecture
Source	GitHub · MIT	Appearance	Appearance

Architecture

Overalls is a monorepo of small services, each named after something or someone, with one NixOS deployment that wires them together. Marshall holds the record of what should exist. Lilly hosts make it physically true and report back. The other services sit at the edges: SSH, DNS, egress, inference and integrations.

Components

Name	Role	What it gives you
Marshall `marshall/`	Web app and control plane (Elixir, Phoenix, Ash)	Accounts with magic links and passkeys, Cedar authorization, machine lifecycle, scheduling, sharing, teams, the browser terminal and agent threads.
Lilly `lilly/`	Host provisioner (Elixir)	Runs Firecracker guests on ZFS behind jailed, isolated networks, with a durable actor for each VM. Guests keep running when Lilly restarts.
Porsche `porsche/`	SSH management gateway	`ssh <gateway> <command>` manages machines with the same account and permissions as the web.
Audi `audi/`	DNS and ingress	Authoritative DNS, guest SSH, and public HTTPS for each machine's web apps.
Brady `brady/`	Egress proxy and cache	Guest downloads go through verified upstreams, and public anonymous responses are cached.
Enrico `enrico/`	Private GitHub mirror	Speeds up checkouts and powers the repository browser.
Galileo `galileo/`	Integration gateway	Named integrations at `<name>.integration.internal`; credentials are added at the edge.
Ziggy `ziggy/`	Inference proxy	`llm.internal` for guests, with no provider keys inside the VM and usage recorded per account.
Lyra `lyra/`	CLI and guest tools (Rust)	The `overalls` CLI: wildcard SSH, `open` for repos, `agent` prompts. It also runs the agent's tools inside the guest.
Browser `browser/`	Toolbar extension	Opens the repository page you're on in your Overalls deployment.
Protocol `protocol/`	Shared wire schemas	Validates the messages services exchange, so their interfaces stay consistent.
Fleet and Nix `fleet/ nix/`	Declarative infrastructure	NixOS modules, host inventory, guest images, secrets, and the host install and enroll tools.

Control plane and hosts

You can run multiple Marshall instances against a shared PostgreSQL. Machine capacity is admitted atomically, so concurrent requests can't overbook a host. Every lifecycle change is a durable operation with an audit trail. Each host's Lilly dials out to Marshall with its own revocable credential, sends capacity reports and receives commands. A generation fence stops a delayed launch from starting a guest after a stop has already been requested.

                 ┌──────────────────────────────────────────┐
 browser ─HTTPS─▶│ HAProxy  TLS, ACME, verified backends    │
                 └────────────────────┬─────────────────────┘
                                      ▼
 ssh ──────────▶ Porsche ───▶ ┌────────────────┐     ┌────────────┐
 overalls CLI ──────────────▶ │ Marshall × 1…N │◀───▶│ PostgreSQL │
                              │ Phoenix · Ash  │     └────────────┘
                              │ Cedar · Oban   │
                              └───────▲────────┘
                                      │ HTTPS, per-host credential
                                      │ reports up · commands down
                        ┌─────────────┴─────────────┐
                 ┌──────┴──────┐             ┌──────┴──────┐
                 │ Lilly host  │     · · ·   │ Lilly host  │
                 │ ZFS · KVM   │             │ ZFS · KVM   │
                 └─────────────┘             └─────────────┘

Marshall decides; Lilly does the work and reports back.

Regions

We recommend running Marshall in a single region. Its instances share one PostgreSQL, and admission, sharing and lifecycle decisions all depend on that database, so keep them close to it. Run several instances in that region for high availability.

Lilly hosts have no such constraint. Each one only needs to reach Marshall over HTTPS, so you can put hosts in every region where your developers work.

Where the traffic goes depends on how you connect. SSH, VS Code over Remote-SSH, and the web apps a machine shares enter through Audi on the machine's own host and stay in that region. The browser terminal and browser editor are relayed through Marshall, over the connection the host dialled out, so they pay the round trip to the control-plane region.

          ┌─ control plane · one region ───────────────────────────────┐
          │                                                            │
          │  HAProxy ─▶ Marshall · Marshall · Marshall ◀─▶ PostgreSQL  │
          │  several Marshall instances for high availability          │
          │                                                            │
          └──────────────────────────────┬─────────────────────────────┘
                                         ▲
                                         │  HTTPS, dialled out by every host
                                         │
            ┌────────────────────────────┼────────────────────────────┐
 ┌──────────┴──────────┐      ┌──────────┴──────────┐      ┌──────────┴──────────┐
 │ WASHINGTON DC       │      │ LONDON              │      │ SINGAPORE           │
 │ Lilly  Lilly  Lilly │      │ Lilly  Lilly        │      │ Lilly  Lilly        │
 │ guests on ZFS       │      │ guests on ZFS       │      │ guests on ZFS       │
 │ Audi: SSH, web apps │      │ Audi: SSH, web apps │      │ Audi: SSH, web apps │
 └─────────────────────┘      └─────────────────────┘      └─────────────────────┘
            ▲                            ▲                            ▲
      developers in                developers in                developers in
      the Americas                    Europe                    Asia-Pacific

One control-plane region, hosts wherever they're needed.

      ┌─ control plane · one region ─────────────────────────────────────────┐
      │  HAProxy ─▶ Marshall · Marshall · Marshall ◀─▶ PostgreSQL            │
      └───────▲──────────────────────────────────────────────────────▲───────┘
              │ web terminal and                  relay over HTTPS,  │
              │ browser editor                 dialled out by Lilly  │
              │                                                      │
 ┌────────────┴────────────┐                          ┌──────────────┴─────────────┐
 │ DEVELOPER IN SINGAPORE  │                          │ HOST IN SINGAPORE          │
 │ browser                 │                          │                            │
 │ ssh, VS Code,           │   direct, same region    │                            │
 │ shared web apps ────────┼─────────────────────────▶│ Audi ─▶ Lilly ─▶ guest     │
 └─────────────────────────┘                          └────────────────────────────┘

SSH and shared web apps go direct; the web interface goes by way of the control plane.

A machine's life

A machine is an identity first and a process second. Its UUID, name, private address, sharing and disk outlive any particular Firecracker process, so stopping, resizing and relocating it don't create a new machine. Cloning does: the copy is private, gets a fresh address and starts without the source's RAM.

  new ─▶ [pending] ─▶ [running] ◀─── start ─── [stopped]
                        │    │                    ▲  │
                        │    └─── stop ───────────┘  │
                        │                            ├─ relocate ─▶ another host
                     resize                          ├─ clone ────▶ new machine
           stop · apply · restart                    ├─ resize ───▶ at next boot
                                                     └─ rm ───────▶ disk deleted

Every transition is a durable request with an ID you can retry.

From inside a guest

Guests reach the outside world only through services that can check, cache and record the traffic. Lateral traffic between guests and to private address ranges is blocked by Lilly's nftables policy. The locked-down customer profile removes outbound networking entirely.

  ┌─ guest ──────────────────────────┐
  │  apt · nix · pip · npm ──────────┼──▶ Brady    proxy, cache ──▶ internet
  │  git clone ──────────────────────┼──▶ Enrico   GitHub mirror
  │  https://llm.internal ───────────┼──▶ Ziggy    ──▶ OpenAI, Anthropic
  │  https://x.integration.internal ─┼──▶ Galileo  adds credentials
  └──────────────────────────────────┘
    secrets stay outside the guest; usage is recorded per account

Credentials are added at the edge, never handed to the guest.

Principles

Declared, reviewed, then applied. Hosts, images, users and secret recipients live in Git. Hosts install from a reviewed plan and update from a pinned branch.
Make it your own. Your fork is yours to change. Patch a component, pin a package or add tools to the guest images with a Nix overlay rather than carrying a long-lived fork of the code.
Secrets never travel in the clear. SOPS and age documents are encrypted to each host's SSH-derived key and to named recovery users. Private keys are generated where they're used.
Authority is checked at execution time. Cedar policies are evaluated when each action runs, not when a page was loaded, so revoked access takes effect on pages that are already open.
Uncertainty is explicit. If a request might not have reached a host, the system asks for deliberate reconciliation rather than guessing.

Decision records

Every design decision is written up as an architecture decision record (ADR), with a review recording the evidence. There are over 170 of them. Some good places to start:

All decision records · Implementation status