Use Forge in Docker

Forge detects Docker containers at startup using two signals — the /.dockerenv sentinel file and /proc/1/cgroup runtime keywords — and automatically activates in ephemeral mode. No seat is reserved; the activation disappears when the container stops.

docker run

Pass the license key as an environment variable. Never bake it into an image.

docker run --rm \
  -e FORGE_LICENSE_KEY="$FORGE_LICENSE_KEY" \
  -v "$(pwd):/repo" \
  ubuntu:24.04 \
  bash -c "
    curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
    export PATH=\"\$HOME/.forge/bin:\$PATH\"
    forge activate \"\$FORGE_LICENSE_KEY\"
    forge health --repo /repo
  "

Dockerfile (single stage)

FROM ubuntu:24.04

# Install Forge binary into the image
RUN curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
ENV PATH="/root/.forge/bin:$PATH"

# Activation is done at container runtime, not build time.
# Pass FORGE_LICENSE_KEY via docker run -e or docker-compose environment.
ENTRYPOINT ["sh", "-c", "forge activate \"$FORGE_LICENSE_KEY\" && forge serve /repo"]

docker run -e FORGE_LICENSE_KEY="..." -v $(pwd):/repo my-forge-image

Multi-stage build

Use Forge in the build stage to check code quality, then discard the license from the final image:

# Stage 1: lint + health check
FROM ubuntu:24.04 AS forge-check
RUN curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
ENV PATH="/root/.forge/bin:$PATH"

COPY . /repo
ARG FORGE_LICENSE_KEY
RUN forge activate "$FORGE_LICENSE_KEY" && \
    forge index /repo && \
    forge health --repo /repo

# Stage 2: production image — Forge is not included, no license exposure
FROM node:22-slim AS production
COPY --from=forge-check /repo/dist /app
CMD ["node", "/app/index.js"]

docker build \
  --build-arg FORGE_LICENSE_KEY="$FORGE_LICENSE_KEY" \
  --target production \
  -t my-app:latest .

The FORGE_LICENSE_KEY build arg is used only in the forge-check stage and is not present in the final image.

docker-compose

docker-compose.yml

services:
  forge:
    image: ubuntu:24.04
    environment:
      # Set FORGE_LICENSE_KEY in a .env file (not checked into git)
      FORGE_LICENSE_KEY: ${FORGE_LICENSE_KEY}
    volumes:
      - .:/repo
    command: >
      bash -c "
        curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh &&
        export PATH=\"\$$HOME/.forge/bin:\$$PATH\" &&
        forge activate \"\$$FORGE_LICENSE_KEY\" &&
        forge serve /repo
      "

# .env (add to .gitignore)
FORGE_LICENSE_KEY=your-key-here

Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: forge-license
type: Opaque
stringData:
  key: "your-forge-license-key"
---
apiVersion: batch/v1
kind: Job
metadata:
  name: forge-health-check
spec:
  template:
    spec:
      containers:
        - name: forge
          image: ubuntu:24.04
          env:
            - name: FORGE_LICENSE_KEY
              valueFrom:
                secretKeyRef:
                  name: forge-license
                  key: key
          command:
            - bash
            - -c
            - |
              curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
              export PATH="$HOME/.forge/bin:$PATH"
              forge activate "$FORGE_LICENSE_KEY"
              forge health --repo /repo
          volumeMounts:
            - mountPath: /repo
              name: source
      volumes:
        - name: source
          persistentVolumeClaim:
            claimName: source-pvc
      restartPolicy: Never

Forge detects Kubernetes via kubepods in /proc/1/cgroup and activates in ephemeral mode automatically.

Overrides

Variable	Effect
FORGE_EPHEMERAL=1	Force ephemeral mode (useful on VMs that look like containers)
FORGE_EPHEMERAL=0	Force persistent mode — seat IS consumed (useful for long-lived container agents)

WSL2 note: Some WSL2 configurations expose Docker cgroup entries even on the host. If Forge incorrectly detects ephemeral mode on your WSL2 machine, set FORGE_EPHEMERAL=0 in your shell profile.