Build from Source

Clone the repository and build Canopy yourself.

Updated
Reviewed

Prerequisites

To build Canopy you'll need:

  • Git v2.30+
  • Node.js v22.12.0+ — The exact version is pinned in .node-version and .nvmrc. Using nvm or fnm is recommended.
  • npm — Ships with Node.js.
  • Platform build tools — Required for compiling the native node-pty module (see below).

Install Xcode Command Line Tools if you haven't already:

xcode-select --install

Clone & Install

git clone https://github.com/canopyide/canopy.git
cd canopy
npm install

The postinstall script rebuilds native modules (node-pty and better-sqlite3) against the Electron runtime. If it fails, run npm run rebuild manually.

Development

Start the dev server with hot reload:

npm run dev

This runs the Vite renderer dev server and the Electron main process together. Renderer changes hot-reload instantly; main-process changes trigger an automatic restart.

Production Build

Build the app without packaging:

npm run build

This compiles the renderer (Vite) and main process (ESBuild) into dist/ and dist-electron/ respectively.

Run the Built App

After building, you can launch Canopy directly without creating an installer:

npx electron .

This uses the "main" field in package.json to find the compiled entry point at dist-electron/electron/main.js. It's the fastest way to test a production build locally.

Tip
Since electron is already a devDependency, npx uses the locally installed version — no extra download required.

Package for Distribution

Create platform-specific installers:

npm run package:mac

Produces a DMG and ZIP in the release/ directory. Builds a universal binary (Intel + Apple Silicon).

You can also run npm run package which auto-detects your current platform.

Tip
Code signing and notarization are disabled for local builds. The binaries work fine for personal use but may trigger OS security warnings on first launch.

Troubleshooting

node-pty build failures

If npm install fails on the native module rebuild:

  1. Make sure you have the platform build tools installed (see Prerequisites above).
  2. Try rebuilding manually: npm run rebuild
  3. On macOS, confirm Xcode CLI tools are current: xcode-select --install

Wrong Node.js version

Canopy requires Node.js 22.12.0+. If you see version errors, switch to the correct version:

nvm install    # reads .nvmrc automatically
nvm use