Egress

Egress is spotlight egress, a container a host starts beside each sandbox for one run and destroys with it. It is the sandbox's only way out. The sandbox is the security boundary gives the reasons.

TopologyCopy Anchor Link

A client in the sandbox that ignores the proxy has no route out. See Inside a sandbox for the proxy and certificate variables.

On start, egress reads /run/spotlight/egress.json from the host and deletes it. It redeems the run's secrets from Spotlight, for up to 1 minute. It then listens, and writes its certificate authority for the host to lay into the sandbox. The host waits up to 90 seconds for it. On SIGTERM it stops within 5 seconds and clears the secret values it held.

Admitted hostsCopy Anchor Link

Host names are compared without regard to case. The Spotlight address, and the storage hosts Spotlight names for the run, are always admitted. * alone is refused at host start.

Refused addressesCopy Anchor Link

Egress checks the address it connects to, after resolving the host name.

TLSCopy Anchor Link

A client that pins certificates fails against an intercepted host. Egress removes Proxy-Authorization from every request it passes on.

What egress adds to requestsCopy Anchor Link

On requests to the host a secret is bound to, egress replaces a request header or query parameter with the secret's value.

Harness keysCopy Anchor Link

A host holds the harness keys in its settings and hands them to egress. The sandbox gets spotlight-egress:<NAME> in their place. Egress replaces the header only when it holds exactly that stand-in, with its prefix, as in authorization: Bearer spotlight-egress:OPENAI_API_KEY.

Egress logs one of these reasons and sends the request without the harness key:

• the host's allow-list does not admit <host>
• it is empty or more than one line

Run secretsCopy Anchor Link

A secret an MCP server's environment names, as secret.<NAME>, is added for the run. The MCP server gets spotlight-egress:<NAME>. Egress replaces the bound header only on requests to the bound host whose header holds that stand-in, with or without the binding's prefix, as in authorization: Bearer spotlight-egress:LINEAR_API_KEY. The stand-in must be the whole value, or come right after the exact prefix. Other requests to the host go out without the secret.

For a secret bound to a query parameter, egress replaces the parameter's value only where it is the stand-in, or the prefix followed by the stand-in, as in ?key=spotlight-egress:MAPS_KEY. The other parameters keep their order and encoding. Egress never logs the full URL. It answers a plain-HTTP or intercepted request it could not pass on with only Egress couldn't reach <host:port>., without the reason. See spotlight_secret and Give an MCP server a secret.

Egress logs one of these reasons and sends the request without the run secret:

• the host holds a key of its own for <host>
• the host's allow-list does not admit <host>
• the host does not let egress read <secret id>
• another secret is already worn in <Header> toward <host>, or in ?<parameter> toward <host> for a query parameter
• it is worn in neither a header nor a query parameter
• it names no header to be worn in, or it names no query to be worn in
• it holds more than one line, so it cannot be worn in a request

On a request to a host egress holds a secret or a harness key for, a header or query parameter holding a stand-in it doesn't put a value in, such as a misspelt name, is removed before the request goes out, and egress logs took a stand-in egress does not hold off a request with the header's or parameter's name only.

Egress takes the secret back out of what the bound host answers before the sandbox sees it. In the Location, Content-Location, Link and Refresh headers, and in a text-like body (JSON, text/*, HTML, XML and form-encoded), every spelling of the value is swapped back to its stand-in: as written, query-escaped, path-escaped and escaped with lowercase hex, each with and without the binding's prefix. A binary body, or one the host compressed, is passed on as it is. Egress asks the bound host for an uncompressed answer. A response it rewrites loses its Content-Length and is sent chunked.

Reading a secret from AWS Secrets Manager fails with:

Egress logs each failure, and the request goes out without that secret.

The run's Spotlight tokenCopy Anchor Link

A run of a setup chat reaches Spotlight's own API. When egress redeems the run, Spotlight mints a workspace token for that run's attempt alone and seals it to egress, like a secret it keeps.

Egress wears it whatever the host's allow-list says, since the Spotlight address is always admitted. When the Spotlight address is plain HTTP, as in http://control-plane:3000 inside the host's network, egress also wears it over plain HTTP, on that address's port only. No other secret is worn over plain HTTP. Egress does not hold the token when the host holds a key of its own for the Spotlight address, or another secret is worn in Authorization toward it, and logs could not hold the run's Spotlight token with the reason.

The token is not listed among the workspace's tokens. A run that reaches Spotlight's API is never reserved for a runner a push pool provisions.

ResponsesCopy Anchor Link

Connections time out after 30 seconds, and TLS handshakes upstream after 15 seconds.

Egress start failuresCopy Anchor Link

These fail the run with The sandbox's egress didn't start. Error: <error>:

If Spotlight refuses to redeem the run's secrets, egress starts with none to add and logs the control plane gave egress nothing to wear. If it cannot reach Spotlight within 1 minute, it logs gave up redeeming the run's secrets; the sandbox goes out wearing none.

Hook callsCopy Anchor Link

A hook that runs on a host is sent from a one-off egress container, spotlight-egress-call-<id>, under the same allow-list and address rules. Only http and https are sent, and redirects are not followed.

LimitationsCopy Anchor Link

• Egress cannot itself send through another proxy.
• A runner a push pool provisions has no egress. A run that uses secrets, or reaches Spotlight's API, is never reserved for one; it waits for a host.
• CURSOR_API_KEY and any other variable not listed under Harness keys enter the sandbox as they are.
• Logins that refresh their own tokens are not added.