Skip to content
Forge Docs

Air-Gapped Activation

Symptoms

Section titled “Symptoms”
  • Your development environment has no outbound internet access.
  • forge activate cannot reach external servers (even though key validation is offline, team invite activation requires a network call).
  • You need to run forge ci in a CI environment that restricts outbound connections.
  • You are deploying Forge in a highly regulated environment (financial, defense, healthcare) with strict network controls.

Two Scenarios

Section titled “Two Scenarios”

There are two distinct scenarios for air-gapped or restricted environments. Read both to identify which applies to you.

Scenario A: Standard Binary in a Network-Restricted Environment

Section titled “Scenario A: Standard Binary in a Network-Restricted Environment”

You downloaded a standard Forge binary but your CI or development machine has restricted network access.

The standard forge activate <key> command validates the license key entirely offline — it performs an Ed25519 signature check using a public key compiled into the binary. No network call is made during activation.

However, two features do require network:

  • Team invite activation (forge activate --team <token>): exchanges the token with the admin portal API. Use forge activate <key> with a full license key instead.
  • Heartbeat: a weekly license health check. The heartbeat is non-blocking and non-fatal — network failure just means the cached result continues to be used. After 60 days without a successful heartbeat, Forge degrades to Community Mode.

For CI environments without persistent ~/.forge:

Use the FORGE_LICENSE_KEY environment variable to provide the license key at runtime without running forge activate:

Terminal window
export FORGE_LICENSE_KEY="eyJrZXki...<base64_payload>.<base64_signature>"
forge ci --repo .

The key is validated in-memory; nothing is written to disk. This is the recommended approach for Docker containers and CI pipelines.

For CI environments where you can pre-bake the license:

Run forge activate <key> once on a machine that has the license file, then copy ~/.forge/license.json into your container or CI environment. Override the data directory if needed:

Terminal window
export FORGE_DATA_DIR=/opt/forge-state
forge activate <key>   # writes to /opt/forge-state/license.json

Then in CI:

Terminal window
export FORGE_DATA_DIR=/opt/forge-state
forge ci --repo .

Scenario B: True Air-Gapped Deployment (Specialized Binary)

Section titled “Scenario B: True Air-Gapped Deployment (Specialized Binary)”

You need a Forge binary that makes zero network calls and works in a completely isolated environment.

Forge offers an air-gapped tier for organizations with strict network isolation requirements (financial services, defense contractors, government, healthcare). Air-gapped binaries are compiled with the --features air_gapped flag, which:

  • Compiles out all network code — no heartbeat, no update checks, no external URLs at build time (the HTTP client library remains linked in v1.3.0 but is never called; full removal is planned for v1.4.0)
  • Embeds the license directly in the binary at compile time — no forge activate step, no ~/.forge/license.json required
  • Licenses expire by calendar year — the binary refuses to run after December 31 of the expiration year; annual renewal produces a new binary

Requesting an Air-Gapped Binary

Section titled “Requesting an Air-Gapped Binary”

Air-gapped binaries are not available for download. They are built per-customer with the license embedded at compile time. Contact sales to request a quote:

air-gapped@forge.ironpinelabs.com

Include:

  • Number of developer seats (minimum 3)
  • Target platforms (Linux x86-64, Linux ARM64, macOS Apple Silicon, macOS Intel, Windows x86-64)
  • Required expiration year
  • Your organization name and contact email

Pricing: $499/user/year, annual billing, minimum 3 seats.

Using an Air-Gapped Binary

Section titled “Using an Air-Gapped Binary”

No activation is required. Copy the binary to each machine and run:

Terminal window
forge --version   # Confirms the binary works
forge license     # Shows embedded license details (tier, seats, expiration year)

The forge config heartbeat show command displays an air-gapped mode notice:

Heartbeat: AIR_GAPPED — no heartbeat endpoint
This binary makes no network calls. License validation is embedded at build time.

Renewal

Section titled “Renewal”

Air-gapped licenses expire at the end of the calendar year specified at build time. Contact sales before your expiration year ends to receive a renewed binary for the next year.

When to Escalate

Section titled “When to Escalate”
  • For Scenario A: Contact support at support@forge.ironpinelabs.com if FORGE_LICENSE_KEY is not accepted in your CI environment.
  • For Scenario B: Contact air-gapped@forge.ironpinelabs.com to discuss air-gapped deployment options.