Install Canopy

Canopy is a single static binary with no runtime dependencies. When it ships, you’ll download it, put it on your PATH, and run canopy --version. That’s the entire install.

At launch: what to expect

Canopy ships as a single static binary per platform:

Platform	Binary name
macOS (Apple Silicon)	`canopy-macos-aarch64`
Linux (x86_64)	`canopy-linux-x86_64`
Linux (aarch64)	`canopy-linux-aarch64`
Windows (x86_64)	`canopy-windows-x86_64.exe`

Each release is accompanied by a SHA256SUMS.txt file for integrity verification. The installer flow will be a standard curl | chmod +x | mv on Unix and Invoke-WebRequest on Windows — no package managers or runtime dependencies required.

Install flow (preview)

The exact URL will be provided at launch. Once you have it, you can set it as an environment variable and the same install commands work on every platform.

# Set this to the download URL provided at launch
export CANOPY_DOWNLOAD_URL="<provided-at-launch>"

curl -fsSL "$CANOPY_DOWNLOAD_URL/canopy-linux-x86_64" -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

# Verify
canopy --version
canopy doctor

The doctor line confirms the binary’s diagnostic harness boots end-to-end. You’ll see a multi-section report covering install detection, active backend (heuristic / Ollama / cloud), data-flow disclosure, and which license-gated features are active in your current mode.

For ARM Linux — Raspberry Pi 4/5, AWS Graviton, Ampere Altra, and similar:

# Set this to the download URL provided at launch
export CANOPY_DOWNLOAD_URL="<provided-at-launch>"

curl -fsSL "$CANOPY_DOWNLOAD_URL/canopy-linux-aarch64" -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

# Verify
canopy --version
canopy doctor

The aarch64 binary is a fully static musl build — no glibc, no shared libraries. It runs identically on Alpine, Debian, Ubuntu, and bare distroless containers.

# Set this to the download URL provided at launch
export CANOPY_DOWNLOAD_URL="<provided-at-launch>"

curl -fsSL "$CANOPY_DOWNLOAD_URL/canopy-macos-aarch64" -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

# Verify
canopy --version
canopy doctor

On Intel Macs, no native build is published yet — Rosetta 2 can run the aarch64 build but performance is degraded; track the issue tracker for native x86_64-darwin progress.

One-shot install with automatic PATH addition for the current user:

# Set this to the download URL provided at launch
$env:CANOPY_DOWNLOAD_URL = "<provided-at-launch>"

# Target install directory (user-local — no admin required)
$installDir = "$env:USERPROFILE\bin"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null

# Download
Invoke-WebRequest `
  -Uri "$env:CANOPY_DOWNLOAD_URL/canopy-windows-x86_64.exe" `
  -OutFile "$installDir\canopy.exe"

# Add to PATH for the current user (persistent — survives new shells)
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$installDir*") {
  [Environment]::SetEnvironmentVariable("Path", "$userPath;$installDir", "User")
  $env:Path = "$env:Path;$installDir"
}

# Verify
canopy --version
canopy doctor

Close and reopen your terminal if subsequent commands don’t find canopy — the $env:Path line above updates the current session, but new PowerShell windows pick up the persisted User-level PATH on launch.

Verify the install

Once installed:

canopy --version

Expected output:

canopy 2.0.x (linux-x86_64)

The platform string (linux-x86_64, macos-aarch64, etc.) confirms which binary you downloaded.

PATH setup (if needed)

If canopy isn’t found after moving the binary:

macOS / Linux
Windows

Add to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"
# Move the binary there instead of /usr/local/bin if you prefer user-local installs

Then source ~/.bashrc or open a new shell.

Search for “Environment Variables” in the Start menu → “Edit system environment variables” → Environment Variables → System variables → Path → Edit → Add the directory containing canopy.exe.

macOS Gatekeeper

On first run, macOS may block the binary with a “cannot be opened because it is from an unidentified developer” dialog.

Fix:

xattr -d com.apple.quarantine /usr/local/bin/canopy

Or: System Settings → Privacy & Security → scroll down → “Allow Anyway” next to the Canopy block.

Activate your license

If you have a license key (from a trial signup or purchase), activate it after install:

canopy activate <your-license-key>