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. Launch it. If the build is not notarized, macOS Gatekeeper may require right-click → Open on first launch.

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.

The standard macOS release is unsigned and not notarized. Automatic updates remain disabled. If Gatekeeper reports that a trusted downloaded build is damaged, the release notes include the quarantine-removal command for private testing.

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: authenticate the Codex CLI for agentic chat 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. 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.