Getting started

RequirementsCopy Anchor Link

• macOS on Apple Silicon (Intel builds are untested)
• Rust to build Anvil from source
• Xcode command line tools (xcode-select --install) if you want Redis, which Anvil builds from source

Ports and password prompts are in System requirements.

Install from sourceCopy Anchor Link

git clone https://github.com/n1crack/anvil && cd anvil
cargo install --path .
anvil --version

This installs the anvil command into ~/.cargo/bin.

The macOS app (optional)Copy Anchor Link

cargo install tauri-cli --version '^2' --locked
cd app && cargo tauri build
open ../target/release/bundle/macos/Anvil.app

The app uses the same ~/.anvil folder and configuration as the CLI. See The macOS app for what it offers.

First runCopy Anchor Link

Install a PHP version (the first one becomes the default) and run setup, which downloads the web server and prints a one-time DNS command:

anvil php install 8.4
anvil setup

PHP is optional if you only serve static sites or apps with their own server (Node.js, Rust, Go, .NET); install those languages with anvil runtime install, see CLI reference.

Resolver setupCopy Anchor Link

macOS sends lookups for *.test to Anvil's DNS server once this file exists. Run the command anvil setup printed; it needs your password once:

sudo mkdir -p /etc/resolver && printf 'nameserver 127.0.0.1\nport 5354\n' | sudo tee /etc/resolver/test

The file name is the domain suffix and the port is dns_port from Configuration. If you change either setting, update the file to match.

Without a password: .localhostCopy Anchor Link

Names ending in .localhost already reach your Mac: macOS and browsers send them to 127.0.0.1 without any setup. Use them instead of .test and skip the step above:

anvil tld localhost        # applications answer at https://<folder>.localhost:8443

In the app: Settings → General → Domain, or Use .localhost instead in the setup bar. .localhost needs no DNS server; anvil tld test switches back.

Add projects and startCopy Anchor Link

anvil park ~/Sites         # every folder in ~/Sites becomes <folder>.test
anvil start                # runs in the foreground; Ctrl-C stops it

Or serve a single folder: cd ~/code/shop && anvil link makes it shop.test.

Trusting HTTPSCopy Anchor Link

The first anvil start creates a local certificate authority in ~/.anvil/data/caddy. While Anvil runs, trust it in another terminal:

anvil trust

This adds the authority to your login keychain (macOS asks for your password). Then open https://<folder>.test:8443. Plain HTTP works on port 8080 too.

UninstallCopy Anchor Link

1. Quit the app or stop anvil start.
2. Run anvil uninstall to see what Anvil changed on this Mac, then anvil uninstall --yes to remove it. That covers the /etc/resolver files Anvil wrote (macOS asks for your password), its certificate authority in your login keychain, the login item, the app's folders in ~/Library and ~/.anvil. ~/.anvil holds your service databases too: back them up first if you need them. Your projects are not touched.
3. Delete Anvil.app and run cargo uninstall anvil.

NextCopy Anchor Link

• Applications: what Anvil detects and how each type runs
• Services: MySQL, PostgreSQL, Redis and Mailpit
• The macOS app