Installation & Setup

Canopy is a review-first workspace for AI coding agents. Download and install Canopy, set up agent CLIs, and complete the first-run setup wizard.

Updated Apr 9, 2026, 10:55 AM

Reviewed Apr 9, 2026, 10:55 AM

What is Canopy?

Canopy is a free, open-source desktop application that hosts AI coding agents in a review-first workspace. Each task can run inside its own isolated Git worktree, so multiple agents work in parallel without stepping on each other's branches. Agents run as CLI processes inside panels you can watch live, and Review Hub is where you inspect, stage, and commit their changes before anything goes upstream. One place to delegate work, watch agents live, and inspect results before anything merges.

If you already run agents from the command line, the mental model maps directly onto what you're doing today:

Terminal workflow	Canopy equivalent
Run an agent in your terminal	Launch an agent panel
Cut a new branch per task	Create a worktree
Run `git diff` to review changes	Inspect the diff in Review Hub
Juggle multiple terminals	Run worktrees in parallel

System Requirements

Canopy runs on macOS, Windows, and Linux. You'll need:

Git — Canopy manages Git worktrees, so Git needs to be installed and on your PATH.
Node.js v18.0.0+ — Needed for installing agent CLIs via npm. Not required if you install agents through other package managers.
One or more AI agent CLIs — At least one of the supported agents installed (see below).

Download & Install

Download the latest release for your platform:

Platform	Format	Architecture
macOS	DMG / ZIP	Universal (Intel + Apple Silicon)
Windows	NSIS Installer / Portable	x64
Linux	AppImage / DEB	x64

Open the .dmg file and drag Canopy into your Applications folder. On first launch, macOS may ask you to confirm since the app is from an identified developer.

Run the NSIS installer and follow the prompts. Alternatively, use the portable version, which requires no installation. Just extract and run. Note that the portable build does not support auto-updates, so you'll need to download new versions manually.

Canopy reads the Windows registry (HKLM and HKCU Environment keys) at startup and supplements your PATH with common tool locations. Tools installed via npm, Git, Scoop, Chocolatey, Volta, pnpm, fnm, and nvm-windows are automatically visible without restarting your terminal session.

For the integrated terminal, Canopy defaults to PowerShell 7 (pwsh.exe) if installed, then falls back to Windows PowerShell 5 (powershell.exe), and finally to cmd.exe.

The DEB package is the recommended option for Ubuntu and Debian-based distributions. It handles desktop integration, AppArmor sandbox configuration, and PATH setup automatically:

sudo dpkg -i canopy_*.deb

The DEB installer creates a /usr/bin/canopy-app symlink and configures an AppArmor profile required for the Chromium sandbox on Ubuntu 24.04+.

Alternatively, use the AppImage on any distribution:

chmod +x Canopy-*.AppImage
./Canopy-*.AppImage

Warning

On Ubuntu 24.04+, AppImage users may see an immediate crash (SIGILL). This happens because Ubuntu restricts unprivileged user namespaces by default. The DEB package handles this automatically. If you prefer the AppImage, you can allow user namespaces for the current session:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

This change resets on reboot. To make it persistent, create a file in /etc/sysctl.d/:

echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-canopy-userns.conf

AppImage on Ubuntu 24.04 also requires libfuse2t64:

sudo apt install libfuse2t64

Tip

Wayland is detected automatically. Canopy reads XDG_SESSION_TYPE at startup and enables native Wayland rendering, window decorations, and IME input support without any flags or environment variables.

Linux uses the native OS title bar rather than a custom frameless window, so Canopy follows your desktop environment's window decoration theme.

Installing Agent CLIs

Canopy runs AI coding agents as CLI processes. Install the ones you want to use:

Claude Code

npm install -g @anthropic-ai/claude-code

Also available via npx @anthropic-ai/claude-code for one-time use without installing globally.

Gemini CLI

npm install -g @google/gemini-cli

Codex CLI

npm install -g @openai/codex

OpenCode

npm install -g opencode-ai@latest

OpenCode can also be installed via platform-specific methods:

curl -fsSL https://opencode.ai/install | bash

Also available via Homebrew:

brew install opencode

scoop install opencode

Also available via Chocolatey:

choco install opencode

curl -fsSL https://opencode.ai/install | bash

Also available via Homebrew:

brew install opencode

Cursor Agent

curl https://cursor.com/install -fsS | bash

irm 'https://cursor.com/install?win32=true' | iex

curl https://cursor.com/install -fsS | bash

After installing, run cursor-agent login to authenticate.

Tip

Canopy automatically detects which agent CLIs are on your PATH and adjusts the UI accordingly. You can check availability in Settings > CLI Agents.

First Launch

When you open Canopy for the first time, a guided setup flow walks you through theme selection, telemetry preferences, and agent installation. The flow has three parts: a welcome dialog, an agent setup wizard, and a getting started checklist. See Welcome Screen for details on what appears after setup.

Canopy enforces a single instance. If you try to open a second copy, it'll focus the existing window instead.

Tip

Your progress through the setup flow is saved automatically. If you close Canopy mid-wizard, it resumes at the same step next time you launch.

Welcome Dialog

The first thing you'll see is a dialog with two theme cards side by side: Daintree (dark) and Bondi Beach (light). Each card shows a mini preview of the Canopy interface so you can see what you're picking. The theme auto-selects based on your OS dark mode setting, and clicking a card applies it immediately. More themes are available later in Settings > Appearance.

Below the theme picker is a Help improve Canopy toggle for anonymous crash reports. No file contents or credentials are ever included.

Click Continue to move on to the agent setup wizard, or Skip to jump straight to the wizard without changing any defaults.

Agent Setup Wizard

The setup wizard checks your system, lets you pick which AI agents to install, and walks you through getting each one set up. A step counter in the top corner tracks your progress (for example, "2 of 5").

System Health Check

The wizard starts by checking the tools Canopy depends on. Checks run in parallel and results appear as they complete:

Git (required) and Node.js v18.0.0+ (required for npm-based agent installation) must be present.
npm (recommended) and GitHub CLI (recommended) are useful but not blocking.

Each tool shows its detected version and a pass, warning, or fail status. For anything missing, expand the How to install section to see platform-specific install commands. An embedded terminal sits below the check results so you can run install commands without leaving the wizard.

Click Re-check after installing a tool to update the results. If a required tool is missing and you continue anyway, the wizard shows a warning first. You can also Skip this step entirely and sort out prerequisites later.

Note

GitHub CLI is recommended but not required. You can skip it during setup and install it later if you need it.

Agent Selection

Next, choose which AI agents you want in your workflow. The wizard lists all supported agents with a brief description of each:

Claude Code — Deep refactoring, architecture, and complex reasoning
Gemini CLI — Quick exploration and broad knowledge lookup
Codex — Careful, methodical runs with sandboxed execution
OpenCode — Provider-agnostic, open-source flexibility
Cursor — Cursor's agentic CLI

Agents already installed on your system are pre-selected. Each one shows an Installed or Not installed badge. Select the agents you want and click Continue to set up any that aren't installed yet. If everything's already in place, the wizard jumps straight to the complete step.

Per-Agent Install Steps

For each selected agent that isn't installed yet, you get a dedicated step showing the install command and a link to the agent's documentation. An embedded terminal is available for running install commands inline.

The wizard polls for CLI availability every 3 seconds. Once it detects the agent on your PATH, the status badge updates to Installed and ready automatically. Click Next to move on, or Skip to handle the installation later.

Setup Complete

The final step lists your installed agents alongside their keyboard shortcuts for quick access:

Agent	macOS	Windows / Linux
Claude Code	`Cmd`+`Alt`+`C`	`Ctrl`+`Alt`+`C`
Gemini CLI	`Cmd`+`Alt`+`G`	`Ctrl`+`Alt`+`G`
Codex	`Cmd`+`Alt`+`X`	`Ctrl`+`Alt`+`X`
OpenCode	`Cmd`+`Alt`+`O`	`Ctrl`+`Alt`+`O`
Cursor	`Cmd`+`Alt`+`U`	`Ctrl`+`Alt`+`U`

Click Finish Setup to close the wizard and start using Canopy.

Tip

You can re-run the setup wizard at any time from Settings > CLI Agents. This is useful if you install new agents later or want to check your system health again.

Getting Started Checklist

After the wizard finishes, a small floating panel appears in the bottom-right corner with four things to try. These are the core workflows in Canopy, and they're a good way to get oriented:

Open your project — Connect a local folder. Everything else flows from here. Clicking this opens the project folder picker.
Ask AI to help with your code — Agents can write code, fix bugs, and answer questions about your codebase. Clicking this opens the agent palette.
Start a parallel task — Work on two things at once without switching branches. Clicking this opens the create worktree dialog.
Stay in the loop — Get product updates and tips in your inbox. Clicking this opens the newsletter signup page.

Items complete automatically as you do the corresponding action in Canopy, so you don't need to come back and check them off manually. When all four are done, you'll see a confetti animation and a success toast.

You can collapse or dismiss the checklist at any time using the header controls. To bring it back later, go to Help > Getting Started.

Opening a Project

Open a project via File > Open Directory (Cmd+O on macOS) or by using the project switcher in the toolbar.

Canopy requires projects to be Git repositories. If you select a directory that isn't a Git repo, Canopy will walk you through initializing one:

Run git init
Optionally create a .gitignore file
Stage all files and create an initial commit

Once a project is opened, Canopy scans for existing worktrees and loads any saved state (terminal sessions, panel layout, recipes).

If you don't have a local copy of the repository yet, you can clone one directly from Canopy. See Cloning a Repository for details.

Recent Projects

Access recently opened projects via File > Open Recent. Projects are sorted by the last time they were opened, and each entry shows the project path for quick identification.

Canopy CLI

The canopy command (macOS and Linux only) lets you open any directory in Canopy straight from your terminal. It works the same way as code . in VS Code. If Canopy is already running, it handles the request internally and opens the directory in a new window without launching a second instance.

Installing the CLI

Install the CLI from within Canopy via Terminal > Install Canopy Command Line Tool in the menu bar.

On macOS, the install creates a symlink at /usr/local/bin/canopy pointing to the bundled CLI script inside the app. This location is on your PATH by default, so the canopy command is available immediately in any new terminal session.

If /usr/local/bin isn't writable (rare on a standard setup), the install falls back to ~/.local/bin/canopy. You may need to add that directory to your PATH manually.

Note

The canopy CLI is not available on Windows. The menu item is present but disabled.

On Linux, the install creates a symlink at /usr/local/bin/canopy. If that path isn't writable, it falls back to ~/.local/bin/canopy (creating the directory if needed).

Warning

On some Linux distributions, ~/.local/bin is only added to your PATH if the directory exists at login time. If you get "command not found" after installing, add it to your shell profile and start a new session:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

AppImage users: Canopy generates a stable wrapper script at ~/.local/share/canopy/canopy-cli.sh instead of symlinking directly into the AppImage mount. This wrapper is created during CLI installation. If you move the AppImage file to a different location, re-run Terminal > Install Canopy Command Line Tool to update the wrapper.

.deb package users: The CLI script automatically resolves the Canopy binary from its installed location (/opt/Canopy/canopy-app or your system PATH).

Usage

Once installed, open any directory in Canopy from your terminal:

canopy .              # Open the current directory
canopy ~/projects/my-app  # Open a specific directory
canopy --status       # Check if Canopy is running
canopy --version      # Print the CLI version
canopy --help         # Show usage information

The --status flag exits with code 0 if Canopy is running and 1 if it isn't, which is useful for scripting.

Tip

The canopy command follows the same project-opening rules as File > Open Directory. If the target directory isn't a Git repository, Canopy will prompt you to initialize one.