Setup & first run

The first time you run Anvil, it walks you through setup — the same four screens whether you do it in your browser or stay in the terminal. By the end you have a provider connected, your security posture chosen, and Anvil ready to work.

Starting setup

Install Anvil (see Install), then run it:

anvil

On a fresh machine — no config.json yet — Anvil detects whether you have a desktop and a browser. If you do, it offers to set up in your browser (the recommended path), and opens a local setup page served by Anvil itself. On a headless box or over SSH, there's no browser to offer, so it runs the same wizard right in the terminal.

Either way it's the same four screens, in the same order, asking the same questions, writing the same config. The browser version is just the roomier way to answer them.

[!NOTE] You can re-run setup any time with anvil --setup, and anvil --check verifies your install, config, vault, and providers are all wired correctly.

Screen 1 — Welcome

The first thing setup asks is your language — and it re-renders the wizard itself in that language immediately, so the rest of setup is in the language you chose. (Anvil ships 60 translations from one shared store, so nothing drifts.)

Then, if a desktop and browser were detected, it asks where to continue: set up in your browser, or stay in the terminal. It asks rather than deciding for you — a terminal user on a desktop can choose the terminal, and a headless user is never told to open a browser they don't have.

Screen 2 — Door & security

This is the most important choice, and it's two decisions that are really one — how Anvil is reachable, and how its credentials are protected.

The door — how you reach and manage this Anvil:

• Local & detached (recommended) — Anvil runs on your machine, reachable only by you (loopback) or your local network. No cloud, no account required.
• Through AnvilHub (SSO) — connect this Anvil to AnvilHub, your command centre: manage it from the web, across every machine you own, with teams, cost tracking, and the rest.

Your choice is saved as the Anvil's control_door, the setting the daemon reads to decide which control plane to start. You can change it later — nothing here is permanent.

If you pick Through AnvilHub, setup helps you sign in or create an account and pair this deployment — the same pairing described in Local vs AnvilHub. You can create an account and pair entirely from the terminal (email, password, and a verification code) — no browser required, even on a headless server.

Security — setup also sets up your vault: a master password that encrypts the credentials Anvil holds (provider keys, tokens). Nothing sensitive is ever written to a plain config file — it lives in the encrypted vault. See Security & the vault.

Screen 3 — Providers

Anvil speaks to 35 AI providers using your credentials. Connect at least one here — you can't finish setup with zero, because Anvil needs a model to run.

Add a provider with an API key, or sign in with OAuth where the provider supports it. Connect several in one pass if you like; any you've already configured show as connected and aren't asked again.

See Models & providers for the full list and how switching works.

Screen 4 — Environment & done

Everything that's left is on one screen — not a chain of prompts:

Confirm, and setup writes your config and marks itself complete. You land in the Anvil workspace, ready to go.

What you have now

• A provider connected (your keys, your machine).
• A door chosen — local, or connected to AnvilHub.
• An encrypted vault protecting your credentials.
• Your layout, theme, and default model set.

Where to next

• Local vs AnvilHub — the two doors in depth, and how to connect to your command centre.
• The workspace — Chat, Coding, and your first real session.
• Models & providers — add more providers and switch models on the fly.