Install Worlds and use the CLI

Worlds includes the local dashboard and the worlds command. The installer bundles Node and the runtime, so Worlds needs no separate Node, npm or Docker installation. Your own agent may still need its normal dependencies.

Get approved access

Apply for the closed beta. After approval, your team receives a download token, the approved release version and its archive checksums. An application acknowledgment does not grant download access.

The installer and these instructions are public. Runtime downloads require your team's token. Enter it only at the terminal prompt or through your CI secret store; keep it out of commands, chat, project files and agent environments. Installed execution works offline without a Sparta account or activation. Revoking a token stops future downloads and updates, without disabling installed copies.

Install in your project

Open a terminal in your agent's project folder, or create an empty folder to explore. Run:

curl -fsSL https://www.usesparta.co/install.sh | sh

Paste your approved download token at the prompt. Its characters are hidden. The installer detects your platform, verifies the signed manifest and archive checksum, installs Worlds in your home directory, and opens the dashboard for the current folder. It does not run a test automatically.

Supported targets are macOS and glibc Linux on ARM64 or x64. Windows and Alpine Linux are not supported by this installer. Installation uses your user account and does not need sudo.

The default locations are:

Item	Location
Installed releases	`~/.local/share/worlds/versions/<version>-<target>/`
CLI launcher	`~/.local/bin/worlds`
Dashboard project data	`.worlds-dashboard/` inside the selected project

Switch from the dashboard to the CLI

The install terminal is hosting the dashboard. Open another terminal tab to keep it running, or press Ctrl+C in the original terminal to stop that host. Closing the browser alone leaves the host running. Saved tests and history stay in your project.

Make the command available in the terminal you want to use:

export PATH="$HOME/.local/bin:$PATH"
worlds --version
worlds --help

The export applies to this terminal session. To keep it for future sessions, add that same line once to your shell's startup file: ~/.zshrc for zsh, or ~/.bash_profile for a Bash login terminal. The installer does not edit shell configuration.

Check Worlds itself using its included known-answer examples:

worlds selftest --server auto

This checks the evaluator, rather than your agent. To test your own agent on the bundled Stripe duplicate-charge task, go to its project folder and run:

worlds try --server auto -- python3 agent.py

Replace python3 agent.py with the command that normally starts your agent, such as node agent.js. The command starts a temporary local runtime, passes the task and world connection to your agent, checks the resulting records, and stops its runtime afterward. Your agent must read the task and use the supplied endpoint settings; see Connect your agent. A reply alone does not establish that it acted on the world.

To create repeatable Stripe tests in your project:

worlds init --agent "python3 agent.py"
worlds passk --server auto --tasks worlds/tasks.yaml --runs 3 --report worlds-report.html -- python3 agent.py

Review the generated tasks, policy and workflow before running them. Use the world references for each connector's supported workflows and qualification limits.

Reopen the dashboard from the same project folder whenever you need it:

worlds dashboard --project .

Install without opening the dashboard

Download the installer, then choose --no-open:

curl -fsSL https://www.usesparta.co/install.sh -o /tmp/worlds-install.sh
sh /tmp/worlds-install.sh --no-open

You still enter the download token privately. After installation, use the CLI commands above. For unattended installation, use --non-interactive and provide WORLDS_DOWNLOAD_TOKEN only to that installation step through your secret store. See Deployment and CI.

Updates and offline installation

Updates are explicit. Obtain the approved version and platform-specific SHA-256 from your release handoff, then pass them with --version and --sha256 to the downloaded installer. Releases stay side by side; the launcher switches only after the new runtime starts successfully. Switching executables does not migrate or roll back project data. Read Storage and upgrades before reopening retained data with another runtime version.

For an offline machine, obtain the approved installer, matching archive, manifest and signature through your team's secure handoff or internal mirror. The installer contains the public verification key. Install those local files with:

sh /path/to/install.sh --archive /path/to/approved-release.tar.gz --manifest /path/to/manifest.txt --signature /path/to/manifest.sig --no-open

Offline installation verifies the signature, checksum, platform and runtime version. It does not require a download token. Keep all files from the same approved release and target.

Troubleshooting

What you see	Next step
`worlds: command not found`	Run the PATH export above, or use `~/.local/bin/worlds --help`.
Terminal stays occupied after installation	It is hosting the dashboard. Open another tab or press Ctrl+C.
Download fails with an access error	Check your approved team token and release version with your Sparta contact. Applying again does not activate a token.
Signature or checksum failure	Stop and obtain the matching approved files. The installer will not switch to unverified bytes.
No requests reached the world	Run `worlds doctor --server auto -- python3 agent.py` with your own agent command and check its endpoint configuration.