Install Canopy

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

Download

macOS (Apple Silicon)

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/forge-macos-aarch64 \
  -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Verify the download:

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/SHA256SUMS.txt \
  | grep forge-macos-aarch64 | sha256sum --check
# Expected: forge-macos-aarch64: OK

Linux (x86_64)

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/forge-linux-x86_64 \
  -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Verify:

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/SHA256SUMS.txt \
  | grep forge-linux-x86_64 | sha256sum --check
# Expected: forge-linux-x86_64: OK

Linux (aarch64)

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/forge-linux-aarch64 \
  -o canopy
chmod +x canopy
sudo mv canopy /usr/local/bin/canopy

Verify:

curl -fsSL https://downloads.canopy.ironpinelabs.com/releases/latest/SHA256SUMS.txt \
  | grep forge-linux-aarch64 | sha256sum --check
# Expected: forge-linux-aarch64: OK

Windows (x86_64)

Download forge-windows-x86_64.exe from the releases page:

Invoke-WebRequest -Uri "https://downloads.canopy.ironpinelabs.com/releases/latest/forge-windows-x86_64.exe" `
  -OutFile "forge.exe"

Move forge.exe to a directory on your PATH (for example, C:\Users\<you>\bin\).

Verify the SHA-256 hash:

# Download checksum file
Invoke-WebRequest -Uri "https://downloads.canopy.ironpinelabs.com/releases/latest/SHA256SUMS.txt" `
  -OutFile "SHA256SUMS.txt"

# Check — expected output shows OK
Get-Content SHA256SUMS.txt | Where-Object { $_ -match "forge-windows-x86_64.exe" }
Get-FileHash forge.exe -Algorithm SHA256
# Compare the two hashes manually

Verify the install

canopy --version

Expected output:

canopy 1.4.0 (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

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.

Windows

Search for “Environment Variables” in the Start menu → “Edit system environment variables” → Environment Variables → System variables → Path → Edit → Add the directory containing forge.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.

Note

Canopy binaries are not yet notarized with Apple. This is on the roadmap. For now, the quarantine attribute removal is the standard workaround used by most developer tools distributed outside the Mac App Store.

Activate your license

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

canopy activate <your-license-key>

Expected output:

canopy: license activated (tier: solo, expires: 2027-04-17)
canopy: machine fingerprint registered (1/1 slots used)
canopy: all 21 MCP tools unlocked

No license key yet? Canopy runs in Community Mode — 1 repo, 3 tools, CLI-only. You can still follow the rest of Getting Started. Run canopy upgrade when you’re ready to start a 14-day free trial.

Next

Index your first repo — one command, and you have a structural model of your codebase.