Install the CLI

simforge is a single binary for Linux, macOS and Windows. It contains no engine or renderer: those come with the runtime, a separate download after you sign in.

Linux and macOS:

curl -fsSL https://simforge.ai/install.sh | sh

Windows (PowerShell):

irm https://simforge.ai/install.ps1 | iex

Use these terminal installation commands. The current CLI binaries are not signed with a macOS Developer ID or Windows Authenticode certificate, so browser-downloaded, quarantined copies are not qualified for Gatekeeper or SmartScreen. Do not disable operating-system security or change PowerShell execution policy to run a downloaded installer file.

The installer picks the build for your machine, downloads it, checks the archive's and the binary's sha256, and installs simforge: into ~/.local/bin on Linux and macOS, into %LOCALAPPDATA%\SimForge\bin on Windows (set SIMFORGE_INSTALL_DIR to change either). It reads no credentials. install.sh edits no shell files: when ~/.local/bin is not on your PATH it prints the line to add (for zsh, the macOS default, to ~/.zshrc). install.ps1 adds its folder to your user PATH. When it finishes it prints the next steps: sign in, accept the agreement, install the runtime, and install ffmpeg, which renders need to write their videos (sudo apt-get install ffmpeg on Ubuntu, brew install ffmpeg on macOS, winget install Gyan.FFmpeg on Windows).

Check the install#

simforge --version

Then sign in. From there, two paths:

• Cloud only. Add --cloud to commands and they run on SimForge's machines; this machine needs no runtime, GPU or ffmpeg. simforge auth status checks the sign-in. See Run in the cloud.
• On this machine. Install the runtime, then check the machine with simforge doctor.

To pin a published runtime release, use simforge runtime install --version VERSION --accept-license. This selects the runtime version; simforge --version reports the CLI version.

Check the machine#

simforge doctor

simforge doctor runs in the runtime, so it needs the runtime installed; before that it stops with runtime_not_installed and says what to do. It checks the machine: the GPU adapter, ffmpeg, the cache folders, free disk and whether the map registry can be reached. Each check reports ok, or what is missing and how to fix it. A machine without a GPU gets a warning, not a failure: simulation and 2D renders run on the CPU. Pass --offline to skip the network check; it is then reported as skipped, never as ok.

What the machine needs#

• On Windows on Arm the CLI runs every command with --cloud; a local command stops with runtime_platform_unsupported and says so. An Intel Mac runs simulation and 2D renders locally and 3D with --cloud.
• Outside the 3D column, render commands stop with gpu_unsupported, gpu_memory_unsupported or gpu_driver_unsupported before any work. An Apple silicon Mac gives three quarters of its memory to the GPU, so a 16 GB Mac renders with 512 px textures and 24 GB or more with full textures. 2D rendering and simulation run on the CPU everywhere.
• Video encodes with ffmpeg (libx264) on macOS and Windows; the NVIDIA hardware encoder is used on Linux. GPU lidar needs Vulkan ray queries, so on macOS lidar uses the CPU reference.
• ffmpeg with libx264 on the PATH to encode videos: sudo apt-get install ffmpeg (Ubuntu), brew install ffmpeg (macOS), winget install Gyan.FFmpeg (Windows), or point SIMFORGE_FFMPEG_BINARY at one. simforge doctor checks it and prints the command; without it renders still write their frames and warn video_encoder_missing.
• Disk for the runtime and the maps you download. The runtime is about 2.7 GB and a map with its 3D environment 5–19 GB.

Running in Docker#

Run the container with the NVIDIA container runtime and its graphics capability, and install the EGL and OpenGL libraries in the image:

docker run --runtime nvidia -e NVIDIA_DRIVER_CAPABILITIES=graphics,compute,utility ...
apt-get install -y libegl1 libgl1        # in the image

Plain --gpus all exposes the GPU for compute only: Vulkan cannot start, and 3D and schematic renders fail with render_failed. 2D renders and simulation need no GPU in the container.

Remove it#

Run simforge logout first if you also want to sign this machine out and delete its stored tokens.

Linux and macOS:

curl -fsSL https://simforge.ai/install.sh | sh -s -- --uninstall

Windows (PowerShell):

& ([scriptblock]::Create((irm https://simforge.ai/install.ps1))) -Uninstall

Use the same SIMFORGE_INSTALL_DIR if you customized it. The uninstall removes only the CLI and its previous binary, not the runtime, maps, credentials or unrelated files. Windows removes its user PATH entry only if the installer originally added it; pre-existing PATH entries and the registry value's type remain unchanged. Reinstall before uninstalling a Windows installation that predates the install receipt. The PowerShell commands run the script in memory; they do not require changing execution policy. On macOS and Linux, remove any PATH line you added yourself if you no longer need it.