Install a host

A host takes work from one pull pool and starts a sandbox for each run it claims. Before you install one, have ready:

• The pool's token. If you don't have one, create a pull pool first.
• Docker, Podman, OrbStack or Colima, running.
• curl or wget, and sha256sum or shasum, for the install script.
• git, which the host uses to keep mirrors of the repositories runs check out.
• An API key for the harness your lines use, such as an Anthropic key for Claude Code.

Install the hostCopy Anchor Link

Run the install script with the pool's token, as the command on the Runners page does. On a self-hosted Spotlight, use your deployment's address in place of app.usespotlight.ai.

curl -fsSL https://app.usespotlight.ai/api/install.sh | SPOTLIGHT_TOKEN=<pool token> sh

To run more than one sandbox at a time, set the capacity in the same command:

curl -fsSL https://app.usespotlight.ai/api/install.sh | SPOTLIGHT_TOKEN=<pool token> SPOTLIGHT_CAPACITY=4 sh

On Linux, run it as root to install a system service with its configuration in /etc/spotlight, or as yourself to install a service for your user, with its configuration in ~/.spotlight. On a Mac, run it as yourself: the host runs as a launchd agent for your user, beside Docker Desktop, OrbStack or Colima.

The script ends with:

spotlight host: serving https://app.usespotlight.ai: this machine shows on the workspace's Runners page once it reports

If you install as yourself on Linux and the machine should keep serving after you log out, run the command the script prints:

loginctl enable-linger $USER

If you want to run the host under your own supervisor instead of a service, add SPOTLIGHT_NO_SERVICE=1 to the install command. The script then prints the command to start it.

Give the host your harness keyCopy Anchor Link

Write the key to sandbox.env, beside the host's configuration.

echo 'ANTHROPIC_API_KEY=<your key>' | sudo tee -a /etc/spotlight/sandbox.env
sudo chmod 600 /etc/spotlight/sandbox.env

The sandbox never sees host.env, so keys go in sandbox.env only. For Codex, Cursor or a Claude subscription, see Give hosts your harness keys.

Restart the hostCopy Anchor Link

The host reads its settings when it starts. Run spotlight host install again to restart the service:

sudo /usr/local/bin/spotlight host install

Check that it is servingCopy Anchor Link

Open Settings from the workspace menu, then Runners. The machine appears in its own row with its name, the pool it came through under Serves, and the harnesses its runner image holds. Its status reads Idle until it claims a run.

If the machine does not appear within a minute, read the host's log:

The host exits with code 3 when Spotlight refuses its token. Check that the token belongs to a pool that still exists and has not been rotated.

RelatedCopy Anchor Link

• Host settings: every setting the host reads.
• Install script
• Why every run gets a fresh sandbox