Anvil

Start with a product or guide

Press Esc to close. Use Tab to move through results.
Desktop · Installation

Installation and setup

Anvil Desktop is an Electron app. You can run a packaged release build or build it from source. Both paths end at the same first-launch flow.

Option A: release build

Release builds are attached to GitHub releases tagged app-v* in the anvil-stack repository.

  1. Download the latest macOS Apple Silicon DMG, or open the latest app-v* release and choose the .dmg or .zip asset manually.

  2. Open the disk image and drag Anvil into Applications.

  3. Open Terminal and run the following command before launching Anvil:

    xattr -dr com.apple.quarantine /Applications/Anvil.app

  4. Launch Anvil from Applications.

Info: macOS signing

Anvil is currently unsigned and not notarized because we do not yet have an Apple Developer account. We are working on it. The command above removes macOS quarantine from Anvil so you can open it. Only run it for a copy downloaded from our official GitHub releases.

Sponsor Anvil on GitHub to support development and help fund Apple Developer membership.

The app-v* release workflows also publish Windows x64 NSIS installers and portable executables, plus Linux x64 AppImage, deb, and pacman packages. Choose the matching asset and inspect the included checksum files on the release page. Wait for the relevant platform workflow to finish if a newly created release does not yet contain its assets.

Automatic updates are currently disabled for the standard macOS release.

Info: using LLMGateway

You need Codex installed to run LLMGateway coding agents in Anvil. In Anvil's LLMGateway setup, choose Install coding engine to let Anvil install and manage Codex for you. Codex runs locally to edit files and execute commands; LLMGateway supplies the models and handles billing.

No ChatGPT login or subscription is required. Connect your LLMGateway account or API key instead. LLMGateway's own billing still applies.

Option B: build from source

Prerequisites:

  • Node.js 22.12.0 or later
  • pnpm 10 (corepack enable is the simplest route)
  • A C/C++ toolchain for the native modules (better-sqlite3, node-pty):
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Windows: Visual Studio Build Tools with the "Desktop development with C++" workload
    • Linux: build-essential, python3, libsecret-1-dev
  • Git 2.30+
git clone https://github.com/anthonyhumphreys/anvil-stack.git
cd anvil-stack/anvil-app
pnpm install
pnpm dev

pnpm install rebuilds the native modules through a postinstall hook, and pnpm dev rebuilds them against the Electron runtime before starting. If either native module misbehaves after a Node or dependency change, rerun pnpm install before debugging anything else.

To produce a local packaged build on macOS arm64:

pnpm run dist:mac:arm64

Artifacts land in dist/.

First launch

On first launch the app walks you through connector setup:

  1. LLM provider: connect LLMGateway and install its Codex coding engine as described above, authenticate the Codex CLI for ChatGPT-backed agent sessions, add an OpenAI key in Settings, or configure Azure AI Foundry through ~/.codex/config.toml plus the referenced API-key environment variable. OpenAI credentials entered in Settings are encrypted before being stored in the local SQLite database.
  2. Optional Apple Foundation Models route: on macOS 26 or later, with Apple Intelligence available and enabled, set Apple Foundation Models to Prefer simple and run Test Apple Models from Settings. On macOS 27, run sudo fm license once to unlock the faster fm CLI backend and image prompts. This only routes short, self-contained helper prompts to the on-device model; repo-aware work still uses the configured backend.
  3. Repositories: connect local checkouts or clone from GitHub/Azure DevOps, then let indexing run.
  4. Optional connectors: Azure DevOps PAT, Linear API key, or Jira token for work items; a Confluence PAT for documentation features.

Desktop state is stored locally. There is no required hosted backend; deleting the app's data directory resets it completely. If you explicitly enable the optional Cloud Workbench, Desktop can connect to the Anvil Cloud endpoint you configure. That bearer is encrypted locally and remote execution state belongs to that control plane.

Optional extras

  • A Nerd Font (for example MesloLGS NF or Hack Nerd Font) makes the built-in terminal render powerline glyphs correctly.
  • The Expo companion app in anvil-app/mobile and the Raycast extension in anvil-app/raycast/anvil pair with a running desktop instance. See Companion surfaces.