Sign in and install the runtime

Sign in with simforge login, accept the runtime’s PolyForm Noncommercial license and SimForge’s account and download terms, and install the closed runtime that simulates and renders.

Downloads need a SimForge account: the runtime and the maps are tied to the account that accepted their agreement. Create one at simforge.ai with your email, or continue with Google or GitHub, then sign in from the CLI. Downloads and cloud runs need a verified email: open the link SimForge emails you after sign-up (Google and GitHub accounts are already verified). To get a new link, sign in at simforge.ai/auth/verify-email and resend it.

Sign in

simforge login                 # opens a browser to approve this machine
simforge login --device        # no browser here (SSH): prints a URL and a short code, then waits
simforge whoami                # account, organization, workspace and scopes

No browser and no terminal that can stay open while you approve (an agent, a flaky SSH session)? Start the sign-in, approve it whenever you like, then finish it from any shell on the same machine:

simforge login --device --no-wait   # prints the URL and the code, and exits
simforge login poll                 # after you approved it: stores the login

login poll answers login_pending while the code is not approved yet (run it again) and finishes a login --device that stopped waiting too.

Headless machines: API keys

A machine nobody can approve a code for (CI, a remote agent) uses an API key. Mint one from a signed-in machine; the secret is printed once:

simforge keys create --name ci --expires-in-days 30

On the headless machine set SIMFORGE_API_KEY to the sfk_… secret (and SIMFORGE_API_URL to the host’s /api/v1 for a host other than simforge.ai). A key acts in the workspace it was created in with at most the scopes of the login that made it, and runs --cloud and hosted commands; runtime and map downloads need simforge login on the machine that installs them. simforge keys list and simforge keys revoke <id> manage your keys.

login waits until you approve the request in a browser. The CLI keeps its tokens in the operating system’s keychain, or in a file only you can read when there is no keychain; the output says which and why. simforge auth status checks the login with the host without printing any token: tokenValid: true means the host accepted it, and emailVerification says separately whether your email is verified (with the page that resends the link when it is not).

A login acts in the workspace of the organization you chose when approving it. Sign in again to switch. simforge logout revokes this machine’s session and deletes its tokens.

Read and accept the license and terms

The runtime is licensed under the PolyForm Noncommercial License 1.0.0. Your SimForge account, downloads and the maps are covered by the SimForge account and download terms. You accept both together. Read the current version first:

simforge runtime license

In short: PolyForm Noncommercial lets you use, change and pass on the runtime for noncommercial purposes as it defines them (personal use, and use by noncommercial organizations such as universities, charities and public research bodies), keeping its license and the Required Notice: line (both ship in the runtime’s share/licenses/). The account and download terms require signing in to download from SimForge and make usage telemetry a condition of using SimForge’s services and downloads. The maps are free for non-commercial use under the SimForge account and download terms and may not be redistributed. Commercial use needs a licence from SimForge. For a commercial licence or questions about the license and terms, write to [e-mail]. The text runtime license prints is what you accept; this summary is not.

Install the runtime

simforge runtime status --available   # what you can install, with download and installed sizes
simforge runtime install --accept-license
simforge runtime status

--accept-license accepts exactly the agreement version and digest the host serves now; without it the install stops with agreement_acceptance_required. The download is checked against its signature and sha256 and only then installed. runtime status reports the installed runtime’s version, protocol, capabilities (for example capabilities.renderModes) and installed: what it is installed for.

--for says what the runtime is for, like maps pull --for:

--for	Installs	Enough for
2d (default for a new install)	the runtime without the 3D actor models and sky: about 50 MB to download, 140 MB installed	scenario new and scenario apply, locations, simulate, render --mode 2d
3d	the whole runtime with the actor models and sky: about 4.3 GB to download	all of the above plus a local render --mode 3d

Without --for, runtime install keeps what is installed (an update of a 3d runtime stays 3d). A local 3D render or preview on the 2D runtime stops with runtime_3d_not_installed and names simforge runtime install --for 3d --accept-license; --cloud renders 3D without either. The same agreement covers both.

Without a runtime, local commands fail with runtime_not_installed, listing every place they looked. Commands with --cloud do not need it.

--root DIR installs the runtime somewhere else. The CLI records the root, so runtime status, doctor and every local command find it there; SIMFORGE_RUNTIME_ROOT overrides it. The download and its unpacking stay inside the root, an install that cannot fit is refused before it starts (disk_insufficient), and the install writes distribution.download.progress and distribution.extract.progress events on stderr while it runs.

Errors you may see

Code	Meaning	Do
not_logged_in	No login for this host	simforge login
session_invalid	The login expired or was revoked	simforge login again
email_unverified	The account’s email is not verified yet	Open the link in your email, or resend it from the page the hint names, then retry
agreement_unavailable	This host publishes no agreement for downloads yet	Check the host (simforge.ai by default)
agreement_acceptance_required	The install was not told to accept the agreement	Read simforge runtime license, then add --accept-license
entitlement_required	This download is not available to your account	Pick another map or version; do not retry