The sandbox is the security boundary
An agent in Spotlight can run commands, edit files and call out to the network. It needs all three to do its work, and each is a reason for a team to decide what the agent can reach. Spotlight gives two kinds of answer to that question, and it matters which one is doing the work.
Permissions are guardrails
A harness profile lets a team say what its agents may do: which files they may read, which commands they may run without asking, and which need a person's approval first. Spotlight writes those rules into each harness in its own terms, and an ask rule turns into an approval in the inbox.
These rules are useful, but the harness enforces them itself, and that is their limit. An agent can still find a way around its own harness's rules, since a rule about one kind of action need not cover another that reaches the same place. A repository can loosen whatever is not enforced, because a harness reads the repository's own settings files on top of the ones Spotlight writes. Spotlight puts the rules that must hold where a repository cannot reach them, where the harness allows that, but the harnesses differ in what they allow.
So Spotlight treats harness permissions as guardrails. They keep a well-meaning agent on the path and give people a say at the points that matter to them. They do not contain an agent that has gone off the path. What contains an agent is the sandbox it runs in and egress, the only way out of it. Limit what agents may do covers the guardrails.
One way out
Each run's sandbox sits on a network of its own that leads nowhere. The only other thing on that network is the run's egress, a proxy container the host starts beside the sandbox for that run alone. Every client in the sandbox is pointed at it, and a client that ignores the proxy has no route out at all.
With one exit, there is one place for the host's rules to apply, and nothing in the sandbox can route around them. Some addresses are refused whatever the host's list says: loopback and link-local, so that a sandbox never reaches the cloud's instance metadata or the host's own identity. A machine's identity lets it claim work and read secrets, and an agent that could borrow it would no longer be contained by anything on this page. Limit where sandboxes can connect covers the allow-list, and the Egress reference lists what egress admits and refuses.
Keeping secrets out of the sandbox
An agent's tools need credentials: an API key for an MCP server, a harness key for the harness itself. The obvious way to give them is to put them in the sandbox's environment. Spotlight does not, because anything in the sandbox can be read by the agent, and so by anything that talks the agent into reading it.
Instead the sandbox gets a stand-in. An MCP server whose environment names the
workspace secret LINEAR_API_KEY sees spotlight-egress:LINEAR_API_KEY where
the value would be. Egress, which is outside the sandbox, holds the real value
for the length of the run. When a request leaves for a host the secret is bound
to, and its header or query parameter holds the stand-in, egress puts the
value in its place. Where the host's answer repeats the value, egress swaps
the stand-in back before the sandbox sees it. The server's request works, and
the agent never had the value to leak.
Without the binding to a host, this would be unsafe. A proxy that swapped in a secret on any request would turn into a credential oracle: the agent could send the stand-in to a server it controls and receive the real value there. Egress adds a secret only to requests to the hosts it is bound to, only for the run that was granted it, and only in place of its stand-in. A request to anywhere else carries nothing egress added, and so does a request to the bound host that doesn't name the secret, such as a script the agent runs.
The stand-in only names a secret; it isn't a password. Everything in the sandbox can read the MCP server's environment, so anything there can still write the stand-in and have the secret used toward its host. What the binding and the stand-in together prevent is the value leaving the sandbox's reach and being sent anywhere else.
The values themselves stay out of reach on the way in too. Values Spotlight
keeps are sealed to a key egress made for that run, so only that egress can
open them. Values kept in AWS Secrets Manager are read by egress itself with
the host's own identity, so the control plane never sees them. The
spotlight_secret reference and Give an MCP server a secret have the details.
Tools a team defines on an integration go further still. When an agent calls one, Spotlight makes the call on its behalf, outside the sandbox, so the credential is never near the agent at all.
Tools Spotlight calls for the agent
A tool an integration offers, whether written out, generated from an API
description or listed by a remote MCP server, is called by Spotlight, not by
the agent. The credential stays with Spotlight, the call can wait for a
person's approval, a hook can refuse it, and the run's journal records it.
An MCP server the harness starts in the sandbox, from a harness profile's
mcpServers, gets none of that: its calls never reach Spotlight. That is why
a remote server belongs on an integration, and a profile's mcpServers is for
servers that must run as a local process.
What a remote server says still reaches the agent. Its tool descriptions are
passed to agents as the server wrote them, and its answers are handed back
as they came. Text in either can carry instructions aimed at the agent, which
is prompt injection, and Spotlight does not filter it. In the docs' view, a
server's descriptions deserve the same trust as its code. Offering a station
only the tools it needs, with tools.include, and keeping approval on for any
tool that changes data, limits what injected text can make an agent do. A tool the server marks as only reading runs without
asking, so a server that marks a writing tool as reading is trusted to that
degree. See MCP servers.
The host decides where its keys may go
Harness keys, such as an Anthropic or OpenAI key, belong to whoever runs the host. The host keeps them out of the sandbox the same way, as stand-ins, and egress adds each one to requests to its model provider's API.
Which key may go to which host is the host's own table, and the control plane has no say in it. An earlier design let the control plane declare it. An audit showed the flaw: a compromised control plane could then aim an operator's key at any host it liked. The field was removed, and a host now adds its keys only to requests to the destinations it knows, and only in place of the exact stand-in. Give hosts your harness keys covers setting them.
Two users inside the sandbox
Inside the sandbox there are two parties. The runner, which runs as root, holds the run's credential, fetches the work, prepares the checkout and talks to the control plane. The agent runs as a separate user, and its environment carries none of the runner's credentials. (Ways in: pools, trusts and tokens follows the run's credential from the host to the runner.)
The separate user is the part that counts. With both in one account, the agent could read whatever the runner held, and the division between them would be cosmetic.
Known gaps
Some things do not yet go through this design, and each is a gap because it leaves a credential or a route outside what egress controls.
Cursor's API key still enters the sandbox. The host has no destination for it in
its table, so it passes into the sandbox as it is. Logins that refresh their own
tokens, such as Codex signed in with ChatGPT or Claude signed in through a
browser, are not added by egress; an API key, or a token from claude setup-token, is. Egress cannot itself sit behind a corporate proxy.
A runner that a push pool provisions has no egress at all. With no egress there is nothing to add a secret to requests, so a run that uses secrets is never offered to a push pool, and waits for a host.
What enters a sandbox can be read
Whatever enters a sandbox can be read by the agent in it, which rules out skills, prompts, attachments and files baked into an image as places for anything secret. A skill, for instance, is text laid into the sandbox for the agent to read. If a station needs something the agent must not see, it belongs in a secret that egress adds to requests, or in a tool that Spotlight calls.