Use Forge in GitHub Codespaces

Forge 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: FORGE_LICENSE_KEY
• Value: your Forge license key
• Repository access: the repos that need Forge

2. Activate in postCreateCommand

Add to your .devcontainer/devcontainer.json:

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

Or if you use a postCreateCommand script:

.devcontainer/post-create.sh

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

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

forge activate "$FORGE_LICENSE_KEY"
forge index .

3. Start Forge in postStartCommand

To start the MCP server automatically when the Codespace resumes:

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

Using a Dockerfile

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

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

# Activation happens in postCreateCommand with the FORGE_LICENSE_KEY secret

How it works

When CODESPACES=true is set, Forge:

1. Skips machine fingerprint computation entirely.
2. Writes ~/.forge/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 forge 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

forge: FORGE_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.

forge: 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 FORGE_EPHEMERAL=0 in remoteEnv if you need the Codespace to hold a persistent seat (unusual).