Move Canopy to a New Machine

The normal path for moving to a new laptop takes two commands: canopy deactivate on the old machine, then canopy activate on the new one. Your license key does not change.

Before you start

• Your old machine must be powered on and reachable.
• You need your license key. canopy license on the old machine confirms the tier and expiration but does NOT print the raw key — keep it from your purchase confirmation email or password manager.
• If your old machine is lost, broken, or wiped, skip to Recover from a dead machine instead.

On your old machine

Step 1. Confirm which license is active:

canopy license

Expected output:

Canopy License
  Tier:       Solo (solo)
  Email:      a***n@example.com
  Seats:      1
  Features:   search, semantic_search, mcp_server, dashboard, workflow_tools, ...
  Issued:     2026-04-17
  Expires:    2027-04-17 (342 days remaining)
  Status:     Active

Step 2. Deactivate this machine. Canopy prompts for confirmation; pass --yes to skip the prompt in scripts.

canopy deactivate

Expected output:

Deactivated. This machine is no longer bound to your license.
Remaining bindings: 0 of 1.

You can now run `canopy activate` on another machine.

Your license key is unchanged. The seat is now free for activation on your new machine.

Note

canopy deactivate contacts the license server to release the binding. You need an internet connection. If you are behind a proxy or firewall, ensure heartbeat.gulfshieldtech.com is reachable on port 443.

On your new machine

Step 1. Install Canopy. See Install Canopy if you have not done this yet.

Step 2. Activate with your license key:

canopy activate <your-license-key>

Expected output:

Canopy license activated.
  Tier:       Solo
  Email:      a***n@example.com
  Seats:      1
  Features:   search, semantic_search, mcp_server, dashboard, workflow_tools, ...
  Expires:    2027-04-17  (342 days)

Features enabled: search, semantic_search, mcp_server, dashboard, workflow_tools, ...

Step 3. Index your repo:

canopy index /path/to/your/repo

That is the entire process. Your new machine is now the active binding for your license.

Troubleshooting

canopy deactivate fails or hangs

If the old machine cannot reach the license server (no network, corporate proxy blocking the endpoint), deactivation may time out.

macOS / Linux

Check connectivity:

curl -I https://heartbeat.gulfshieldtech.com/health
# Expected: HTTP/2 200

If the request times out or returns an error, the server is not reachable from that machine. Use the portal self-service path instead — see Recover from a dead machine.

Windows

Check connectivity in PowerShell:

Invoke-WebRequest -Uri "https://heartbeat.gulfshieldtech.com/health" -Method Head
# Expected: StatusCode 200

If this fails, use the portal self-service path instead — see Recover from a dead machine.

canopy activate says “seat limit reached”

This means the old machine’s binding was not fully released. Two recovery paths:

1. Go back to the old machine and run canopy deactivate again, then retry activation on the new machine.
2. Use the portal at https://canopy.gulfshieldtech.com/portal/login to manually revoke the old binding. See Recover from a dead machine.

Tip

If a binding has been inactive for 90 days, canopy activate will offer to evict it automatically. You do not need to contact support in that case — just confirm the prompt.

canopy activate says “invalid key”

The license key may have been re-issued during an eviction on another machine. Check your original purchase confirmation email for the key, or retrieve it from the portal. The CLI does not echo the raw key — canopy license only prints tier, email, expiration, and features metadata, never the key itself, so you cannot recover the key from a working install.