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 and run
./forge doctor. - Activate 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.
macOS Installation
Use the Lima-managed data plane
Choose the macOS archive matching Apple Silicon or Intel. Forge provisions a persistent Lima VM; the fixed local lab ports remain Web 16080 and API 16081.
tar -xzf forge-<version>-macos-<architecture>.tar.gz cd forge-<version>-macos-<architecture> ./forge doctor ./forge install
macOS requires Lima 2.x and at least 12 GB free disk. The default VM is 4 CPUs, 6 GiB RAM, and a 20 GiB sparse disk.
Linux Installation
Run the lab on the native kernel
Choose the Linux archive matching amd64 or arm64. Install Docker Engine and Docker Compose, then make the MPLS/VRF modules available.
sudo modprobe mpls_router mpls_iptunnel mpls_gso vrf tar -xzf forge-<version>-linux-<architecture>.tar.gz cd forge-<version>-linux-<architecture> ./forge doctor ./forge install
License Activation
Authorize the local lab
./forge license activate <your-Forge-license-key> ./forge license status ./forge license entitlements
Activation stores local authorization state. It does not upload lab telemetry, router state, or incidents to the Online Forge Portal.
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.
Updating Forge
Check then download a signed update
./forge update check ./forge update download
Verify the downloaded release checksum before use. Return to the Online Forge Portal to select a new platform bundle when required.
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.