Getting Started
Onboarding journey
- Create an Online Forge Portal account.
- Receive a Forge license with lab access.
- Select a signed Forge release for your platform and architecture.
- Extract the bundle.
- Activate and install every signed runtime component with
./forge license activate <your-Forge-license-key>. - Run
./forge start, then openhttp://localhost:16080. - Start your first Practical Exercise in the Offline Forge Lab.
Installation
One download page for every supported platform
The authenticated Download page presents macOS Apple Silicon, macOS Intel, Linux arm64, and Linux x86_64 archives together. Each complete signed package contains the exact tested application and runtime images; activation verifies and imports them without a registry login.
On macOS, run Forge as the normal login user and never use sudo ./forge; Lima cannot run in a root session. Linux activation requests sudo only when required kernel settings are missing.
Starting and Stopping Forge
Reuse the local lab between sessions
./forge start ./forge stop ./forge status ./forge doctor
stop preserves the macOS Lima VM. start reuses it.
Web UI Guide
Operate from the local portal
Open http://localhost:16080. Use Book and Practical Exercises for instruction, Lab for the active topology and guided exercises, Events for normalized event history, and License for local authorization status. Router console access and incidents are available only here, not in the Online Forge Portal.
CLI Guide
Inspect and validate
./forge lab list ./forge lab current ./forge validate-control-plane ./forge router sp1 "show isis neighbor" ./forge events --source bgpls ./forge diagnose-flaps
The router command wrapper accepts only approved read-only operational commands.
Switching Labs
Run one profile at a time
./forge lab list ./forge lab switch sp-network ./forge lab switch ai-fabric ./forge lab validate ./forge lab reset
Switching replaces only lab-specific containers and retains shared Forge services where practical.
Running Scenarios
Use controlled changes
./forge scenario list ./forge scenario start link-pe1-sp1-down ./forge scenario status ./forge scenario reset
Scenarios use only predefined actions and deterministic resets.
Completing Incidents
Prove the failure and recovery
./forge incident list ./forge incident start pe1-sp1-link-failure ./forge incident status ./forge incident remediate ./forge incident report
Included incidents ask you to gather structured evidence, select answers, approve safe remediation, and verify recovery in the local lab.
Troubleshooting
Check the local prerequisites first
./forge doctor ./forge status ./forge diagnose-flaps --seconds 0 ./forge scenario status
Confirm host resources, ports, image architecture, container health, and the exact protocol condition before changing resources or resetting the lab.
Upgrading Forge
Run the updater from the currently installed source release
Use license activate only for a first installation. Never run an upgrade from a newly downloaded target package.
macOS: activation copies the authoritative runtime to this persistent directory. Replace <installed-version> with the version reported by ./forge update check:
cd "$HOME/.local/share/forge/runtime/<installed-version>" ./forge version ./forge update check ./forge upgrade ./forge start # After the first post-upgrade start, use the new versioned runtime: cd "$HOME/.local/share/forge/runtime/<new-version>" ./forge status
Linux: return to the extracted directory where the currently installed version was activated:
cd /path/to/forge-<installed-version>-linux-<architecture> ./forge version ./forge update check ./forge upgrade ./forge start ./forge status
Linux upgrades replace the product files in the same installed directory; the directory name may retain the source version, while ./forge version reports the authoritative installed version.
./forge version must show the installed source version before you continue. The upgrade command selects a compatible entitled release, downloads and verifies the complete signed bundle, shows downtime and rollback availability, asks for confirmation, and performs the upgrade. You do not need to run update download first, open the target archive, or run its install.sh.
To request a specific compatible release, pass its version—not a file or installer path:
./forge upgrade --target <target-version>
Do not run ./forge license activate to replace an installed version. Activation cannot bypass signed database migrations and will refuse a cross-version replacement. A supported upgrade preserves the license, device identity, PostgreSQL data, active lab selection, learning progress, incident and scenario history, evidence, and local preferences.
Clean replacement
A clean replacement is destructive and is not an upgrade. It permanently removes local labs, PostgreSQL data, progress, incidents, evidence, and rollback files.
./forge license deactivate ./forge destroy --yes rm -rf "$HOME/.local/share/forge/runtime" rm -rf "$HOME/.config/forge/rollbacks" "$HOME/.config/forge/downloads" rm -f "$HOME/.config/forge/installation.json"
Afterward, extract the new archive and run its new-install activation and start commands. On Linux, remove the old extracted directory after leaving it.
Upgrade recovery
Read the error before changing installation state
If an upgrade is interrupted after it begins, follow the command printed by Forge—normally ./forge rollback. Do not destroy the lab, delete ~/.config/forge, reactivate the license, or edit installation.json; those actions can remove the recovery information needed to preserve local data.
If ./forge upgrade reports INSTALLATION_STATE_INVALID immediately after a rejected cross-version activation, use a corrected Forge updater before retrying. The corrected updater verifies the signed installed release and safely restores only this known pre-install refusal state. Contact Forge support with the installed version and exact error text; never send your License ID, activation token, device fingerprint, or the contents of ~/.config/forge.
Uninstalling or Destroying the Lab
Remove local lab data intentionally
./forge destroy
This removes the macOS Lima VM and its lab data, or the corresponding native lab resources on Linux. It does not revoke your Online Forge Portal account or license.