// Get started
Install the CLI
Install the simforge command line on Linux, macOS or Windows and check the machine with simforge doctor.
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 | shWindows (PowerShell):
irm https://simforge.ai/install.ps1 | iexUse these terminal installation commands. New macOS releases use Developer ID signing and notarization; older Mac releases and Windows binaries may still be unsigned. macOS checks a bare executable's notarization ticket online, so its first launch needs internet access. 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).
On Windows, keep the default short %LOCALAPPDATA%\SimForge\bin prefix for shell use. The installer can write longer paths, but PowerShell 5.1 and some .NET launchers can reject executable paths over 260 characters even when installation succeeded; choose a shorter SIMFORGE_INSTALL_DIR rather than changing system policy.
Check the install#
simforge --versionThen sign in. From there, two paths:
- Cloud only. Add
--cloudto commands and they run on SimForge's machines; this machine needs no runtime, GPU or ffmpeg.simforge auth statuschecks 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 doctorsimforge doctor runs right after the install, with or without the runtime. It checks the sign-in, the runtime (and every place it looked when there is none), free disk for the runtime and the maps, whether the GPU supports local 3D and is free right now, ffmpeg, the map cache and the host's map catalogue; with the runtime installed it adds the runtime's own checks (the GPU adapter it would render on, sky plates, the open-file limit, the actor models). Each check reports ok, warn, fail or skipped, and every warn or fail comes with its fix. A machine without a runtime or a GPU gets warnings, not failures: --cloud needs neither, and simulation and 2D renders run on the CPU. --offline makes no network request; the checks that need one are reported as skipped, never as ok. A failing check you cannot fix? simforge feedback --include-doctor "<what you were doing>" sends us the checks (what it sends).
What the machine needs#
| Linux | macOS | Windows | |
|---|---|---|---|
CLI and --cloud | x86_64, glibc 2.39 or newer (Ubuntu 24.04 or later) | macOS 13 or later, Apple silicon or Intel | Windows 10 (1803) or 11, x64 or Arm64 |
| Local runtime: simulation, 2D | x86_64 | Apple silicon or Intel | x64 |
| Local 3D and schematic | NVIDIA, Vulkan, 8 GiB, driver 570 or newer | Apple M3 or newer with 16 GB of memory or more | NVIDIA, Vulkan, 8 GiB, driver 570 or newer |
- On Windows on Arm the CLI runs every command with
--cloud; a local command stops withruntime_platform_unsupportedand 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_unsupportedorgpu_driver_unsupportedbefore 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. ffmpegwith libx264 on thePATHto encode videos:sudo apt-get install ffmpeg(Ubuntu),brew install ffmpeg(macOS),winget install Gyan.FFmpeg(Windows), or pointSIMFORGE_FFMPEG_BINARYat one.simforge doctorchecks it and prints the command; without it renders still write their frames and warnvideo_encoder_missing.- Disk for the runtime and the maps you download. For authoring, simulation and 2D renders: the 2D runtime (about 140 MB installed) and each map's 2D install (tens of MB);
--cloudneeds neither. A local 3D render needs the 3D runtime (about 4.3 GB to download, 5.2 GB installed) and the map with its 3D environment (about 5 to 22 GB to download).simforge runtime status --availableandsimforge maps show <map>give the exact sizes; an install needs its download and its unpacked size free at once, and is refused before downloading when they do not fit (disk_insufficient). - A shared or busy GPU:
SIMFORGE_GPU=nonekeeps local work off it. 3D and schematic renders are then refused (gpu_disabled; render them with--cloud), and 2D renders and simulation run on the CPU as always.
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 imagePlain --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 -- --uninstallWindows (PowerShell):
& ([scriptblock]::Create((irm https://simforge.ai/install.ps1))) -UninstallUse 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.