What runs where

The work is split between two sides. The hosted service at https://app.usespotlight.ai keeps track of it, and the AI agents that do it run on computers the team provides, which Spotlight calls hosts. A self-hosted Spotlight is split the same way, at its own address, with its own settings.

A run is one agent's session on one task. For each run, the host starts a fresh, isolated container called a sandbox, and deletes it afterwards.

What goes on which side comes down to one question: which side needs to hold what, and which side can do without it.

Spotlight's sideCopy Anchor Link

Spotlight keeps everything that people and computers share:

• The workspace's configuration: its lines and stations, and the settings around them, such as the agent setups stations use (harness profiles), the connections to other services (integrations), the rules that call a team's own services (hooks), and the ways hosts are allowed to take work (pools and trusts).
• The work itself: tasks, runs and the record of what each agent did, the inbox, and chats.

Spotlight decides which run goes to which host, receives events from GitHub and other services, and makes the calls behind the tools a team defines. It also keeps the secrets a team stores with it, encrypted.

It holds the workspace's connection to GitHub, too. The GitHub App that can clone and push to the team's repositories is installed for Spotlight, and its access is never handed to a host (Where each credential stays explains how runs reach GitHub without it).

Every sandbox, and every command an agent runs, is on the team's hosts.

The team's sideCopy Anchor Link

A host is any computer running spotlight host. It joins a pool, a group of hosts that take a team's runs, either with the pool's token or, on a cloud platform, by proving its identity through a runner trust. The host asks Spotlight for work, and for each run it takes, it starts two containers on a private network of their own:

• The sandbox, where the code is checked out and the agent does its work.
• The run's egress, a gatekeeper container that is the sandbox's only way out to the network.

When the run ends, both are deleted. Why every run gets a fresh sandbox explains that choice. A run that asks a person keeps its sandbox, and its place on the host, for a few minutes in case the answer comes quickly. After that it is set aside, and any of the team's hosts that can take the run picks it up again when the answer arrives.

The host is also where the team's decisions about its own machines live. It decides which container images it will run, which servers sandboxes may reach, which secrets in the team's AWS account egress may read, and which of the team's model API keys it holds. None of these is Spotlight's to set. They are settings on the host (Host settings).

The host only connects outCopy Anchor Link

Spotlight never connects to a host. Every exchange starts with the host: it asks for work, reports what it is doing, and asks again. Calls meant for the team's private network, such as a hook to an internal service, reach the host the same way: the host collects them (Hooks and reactions).

The reason is where hosts need to run. A computer that only makes outgoing connections works behind a home router or a company firewall with nothing opened up, so a laptop can take work as well as a cloud server can.

The one exception is a push pool, where Spotlight calls one of the team's endpoints to start a machine for each run. Ways in: pools, trusts and tokens compares push pools with hosts.

One program, several rolesCopy Anchor Link

Everything Spotlight ships for the team's side is a single program, spotlight. On a host it runs as spotlight host, inside a sandbox as spotlight runner, the part that prepares the run and reports back to Spotlight, and in the run's egress as spotlight egress. The agent uses it for the commands it reports with, such as spotlight handover.

Where each credential staysCopy Anchor Link

The host's own credential, its pool token or its cloud identity, stays on the host. When the host takes a run, Spotlight gives it a credential for that run alone, and that is all the sandbox gets. If someone took over a sandbox, that credential would let them do only what the run itself may do, such as report on it and reach its line's repositories, and only until the run ends. They could not take other runs or act as the host. Ways in: pools, trusts and tokens lists each kind of access and what it costs if it leaks.

Git goes through Spotlight. Every clone, fetch and push from a sandbox goes to Spotlight with the run's credential, and Spotlight carries it to GitHub with the workspace's own GitHub App. Spotlight answers only while the run still holds its task or chat, and only for the repositories the run's line names. So the credential that can push to the team's repositories never leaves Spotlight, and a run's access to GitHub ends when the run does.

Model API keys, such as an Anthropic key, go the other way. Spotlight calls them harness keys. They stay on the host and never reach Spotlight. The sandbox never sees the Anthropic or OpenAI keys the host holds: it holds a placeholder, and the run's egress swaps in the real key on requests to the model provider. The spotlight program fixes which provider each of those keys may go to, and the host's list of servers sandboxes may reach can still refuse it. The reasons, and the harness keys that still enter the sandbox, are in The sandbox is the security boundary.

Secrets needed by an MCP server, a tool server the agent connects to, are split between the two sides. A secret stored with Spotlight is encrypted to a key that the run's egress created, so only that egress can open it. A secret in the team's AWS Secrets Manager is read by egress directly, as the host, and Spotlight never sees it.

What still passes through SpotlightCopy Anchor Link

The split is about where agents run and who holds which credentials. It doesn't keep a team's code away from Spotlight:

• The code passes through Spotlight on its way to and from GitHub, as above. A host also keeps a copy of each repository it has worked on, refreshed through Spotlight, and lends it to its sandboxes read-only.
• When a run stops to wait for a person, and when it ends, the runner saves the task's working files (its checked-out code and the agent's conversation) to Spotlight's storage. When the run carries on after the answer, or a later run of the task starts, it restores them on whichever host takes it up (How a conversation survives between runs).
• The record of what the agent said and did is sent to Spotlight as it happens, which is how the run page shows it live.

A team weighing where its code may go should count these too. What stays entirely on the team's side is where the agent runs, what network it can reach, and the model keys it uses.