Use Canopy in GitHub Codespaces

Canopy detects Codespaces automatically via the CODESPACES=true environment variable and activates in ephemeral mode — no seat is reserved for the Codespace. You can spin up as many Codespaces as you like on a single license.

Quick setup

1. Add the license secret at the org level

In your GitHub organization (or personal account): Settings → Codespaces → Secrets → New secret

• Name: CANOPY_LICENSE_KEY
• Value: your Canopy license key
• Repository access: the repos that need Canopy

2. Activate in postCreateCommand

Add to your .devcontainer/devcontainer.json:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "postCreateCommand": "curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh && canopy activate \"$CANOPY_LICENSE_KEY\"",
  "remoteEnv": {
    "CANOPY_LICENSE_KEY": "${localEnv:CANOPY_LICENSE_KEY}"
  }
}

Or if you use a postCreateCommand script:

.devcontainer/post-create.sh

#!/usr/bin/env bash
set -euo pipefail

curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh
export PATH="$HOME/.canopy/bin:$PATH"

canopy activate "$CANOPY_LICENSE_KEY"
canopy index .

3. Start Canopy in postStartCommand

To start the MCP server automatically when the Codespace resumes:

{
  "postStartCommand": "canopy serve . &"
}

Using a Dockerfile

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04

# Install Canopy during image build (no license needed at build time)
RUN curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh

# Activation happens in postCreateCommand with the CANOPY_LICENSE_KEY secret

How it works

When CODESPACES=true is set, Canopy:

1. Skips machine fingerprint computation entirely.
2. Writes ~/.canopy/ephemeral.json instead of binding to a seat.
3. Sends a short-lived heartbeat (1-hour cache) so the admin portal shows Codespace usage in the analytics tab.
4. Caches the session in /tmp/forge-session-cache.json — subsequent canopy invocations in the same Codespace skip the network call entirely.

This does not count against your seat limit. The license key in the org-level secret is shared across all Codespaces without consuming extra seats.

Troubleshooting

canopy: CANOPY_LICENSE_KEY is not set — the secret was added at the account level but not enabled for this repository. Go to Settings → Codespaces → Secrets and add the repo to the secret’s access list.

canopy: ephemeral mode detected but license is expired — renew the license at the portal. The old key continues to work until the grace period ends.

Force non-ephemeral mode — set CANOPY_EPHEMERAL=0 in remoteEnv if you need the Codespace to hold a persistent seat (unusual).