Anvil beta
DocsRun Anvil on your own server
Overview
Get started
IntroductionQuickstart: code reviewQuickstart: CI runnersConnect your agent
Guides
Add repositoriesMove workflows to Anvil runnersHost a repository on AnvilUse the pull request workspaceBlock merges with pre-merge checksTeach Anvil your rulesLet Anvil change codeFind failing, slow and flaky CIWatch CPU and memoryInvite your teamRun Anvil on your own server
Reference
ConfigurationCommandsHow reviews workRunner sizes and labelsMCP serverEnvironment variables
More
Security and dataFAQ
Docs/Guides

Run Anvil on your own server

One command sets up a server: Anvil, its Postgres database and the git server behind hosted repositories, and, if you ask for them, runners for GitHub Actions with limits that keep CI from taking the server down, an always-on virtual machine where coding agents keep working while your laptop is off, and a private network to reach it from your phone. Every step checks what's already there first, so running it again repairs instead of starting over. This page is the short version; docs/SELF-HOSTING.md in the repository has every option.

What you need #
Server Linux with Docker and the Compose plugin; 2 vCPU and 4 GB of memory to start. Runners, the agent VM and private access need Ubuntu 22.04+ or Debian 12+
Agent VM A server with hardware virtualisation (/dev/kvm) and 16 GB of memory or more. Most cloud servers don't offer it; dedicated servers do
Domain Two names pointing at the server: anvil.example.com and git.anvil.example.com (and headscale.anvil.example.com for private access)
Ports 80 and 443 (web and certificates), 2222 (git over SSH), 3478/udp for private access
Keys An Anthropic API key. SMTP for email and a GitHub account for the GitHub app are optional

Install #

  1. Get the code:

    bash
    git clone https://github.com/davidwickerhf/anvil.git /srv/anvil
cd /srv/anvil

  2. See what the install would do (nothing changes yet). Leave out the options you don't want:

    bash
    scripts/anvil plan --domain anvil.example.com --email you@example.com --with-runners --with-agent-vm --with-headscale

  3. Install. It checks the server first, asks for your Anthropic key without showing it, and ends with the DNS records to create and what's next:

    bash
    scripts/anvil install --domain anvil.example.com --email you@example.com --with-runners --with-agent-vm --with-headscale

  4. Open the one-time link for the first admin, choose a login and enter your email address:

    bash
    cd deploy/compose && docker compose logs anvil | grep -A2 "No admin yet"

  5. With the agent VM: sign its tools in. You only see links and codes to open on your own device; nothing you type is shown or saved in a log:

    bash
    scripts/anvil login

  6. With private access: add your phone and pair the T3 Code app with the VM:

    bash
    scripts/anvil add-device

scripts/anvil status shows what's installed, and scripts/anvil uninstall <part> removes one part again (the VM's disk only with --purge).

After the first sign-in #

Settings → Setup shows what's configured (git server, webhook, mail, GitHub, runners, SSH, backups) and what to do about anything missing. Then:

Back up and move servers #

bash
scripts/anvil-backup --keep 14     # databases, repositories, LFS, SSH host keys, settings
scripts/anvil-restore <archive>    # on the new server; --domain new.example.com if the address changes

The SSH host keys move with the archive, so people's git clients keep trusting the server. When the address changes, the restore lists what to update: the GitHub app's URLs, people's clone remotes and MCP clients.

Runners #

Jobs with runs-on: anvil-* need the runner manager: install with --with-runners (or set COMPOSE_PROFILES=proxy,runners). It controls Docker on the machine it runs on, so run other people's workflows on a separate machine. See Runner sizes and labels and Security and data.