Browse all docs

Anvil Desktop / Basics

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 (macOS Apple Silicon)

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

  1. Download the .dmg (or .zip) for macOS arm64 from the latest app-v* release.
  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.

Other platforms do not have published builds yet; use the source path below. The packaging config supports Windows (NSIS, portable) and Linux (AppImage, deb) targets for local builds.

Option B: build from source

Prerequisites:

  • Node.js 20 LTS 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: add an Azure AI Foundry or OpenAI key in Settings. Credentials are encrypted before being stored in the local SQLite database; no .env file is involved.
  2. Repositories: connect local checkouts or clone from GitHub/Azure DevOps, then let indexing run.
  3. Optional connectors: Azure DevOps PAT, Linear API key, or Jira token for work items; a Confluence PAT for documentation features.

Everything is stored locally. There is no hosted backend; deleting the app's data directory resets it completely.

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.

Read next

Anvil DesktopDesktop architecture