Egress and credentials

An agent in a sandbox can usually reach any host and hold any credential it is handed. Two controls narrow both: an allowlist of hosts, and credentials that exist only where the request leaves.

overlane egress policy set --allow registry.npmjs.org --allow api.github.com
overlane egress check --host registry.npmjs.org
overlane egress grant --task task-12 --host api.github.com --secret GITHUB_TOKEN
overlane egress events --outcome denied

The allowlist

The default is deny. With no rule nothing is reachable. A rule is a host name, with optional ports (443 unless you say otherwise), or a wildcard:

• registry.npmjs.org matches exactly that host.
• *.example.org matches any subdomain at any depth and never the apex example.org.
• A wildcard over a top-level domain or a shared-hosting domain (*.com, *.github.io, *.amazonaws.com) is refused, because anyone can register a name under those. An exact host there is fine.

Host names are compared lower case, with a trailing dot removed. These are denied whatever the rules say, in every mode:

• A raw IP address in any notation: dotted, decimal (2130706433), octal, hex, IPv6.
• Cloud metadata services such as 169.254.169.254 and metadata.google.internal.
• Internal names (localhost, .internal, .local) and names with no dot.
• A listed name that the enforcement point resolved to a private or loopback address, so a name that points inside is refused.

--mode report records a host with no rule and allows it, so you can learn what a job needs, then switch to enforce. Changing the allowlist is a policy change.

Every decision is stored as a row: host, port, outcome, reason, task and run. Never a URL path, a header or a body. overlane egress events lists them.

Per-task credentials

A grant lets one task use one named secret on named hosts for a limited time.

• The grant names the secret, such as GITHUB_TOKEN. It has no field for the value.
• The hosts must already be on the allowlist, and a credential goes out only on port 443.
• The egress proxy attaches the value to a request for a granted host (as Authorization: Bearer or a header you choose). The agent never receives the value, and it is not written to the job’s environment, a log or the workspace.
• The grant resolves only for its own task and project, before it expires, and until it is revoked. overlane egress revoke ends it at once, and a runner revokes a task’s grants when the task ends.
• A host that is merely tolerated in report mode gets no credential.

When a grant needs an approval

A grant for one task, named hosts and at most an hour is an ordinary action. A grant is class secrets when it is wider than one task (--scope project or team), lasts longer than an hour, or opens a wildcard of hosts. An agent asks for an independent agent’s approval in that case: the refusal names the subject to approve, another agent answers with evidence, and the first agent retries with OVERLANE_APPROVAL set. The approval covers exactly that grant, once (see Autonomy). A person does not need one.

Leak checks

overlane egress scan sends the names of the files in your workspace, never their contents, and reports files that usually hold a credential: .env, .npmrc, private keys and cloud credential files. It exits 6 when it finds one.

Inside the runner, a scan of a job’s logs and files looks for any value minted for the project’s grants in plain, base64, hex and percent-encoded form, and for credential-shaped strings. A finding names the place and the form, never the value. The platform also refuses any API request whose body carries a credential, which is why log scanning runs in the runner and not over the API.

Runners

Native CI and the agent sandbox are enforcement points. A runner calls the Worker in process, not over HTTP, so an agent token cannot ask for a credential: it fetches the policy when a job starts, evaluates each outbound connection, resolves a grant for a granted host, scans the logs when the job ends and revokes the task’s grants. The policy, the checks and the event log work without a runner. While no runner secret store is connected, creating a grant answers 503 with live_leg_pending.

Agent use and the override

An agent asks for the grant it needs for the task it works on and gets only that. A person can read the policy, the grants and every decision, change the allowlist, revoke any grant, and make a wide grant without an approval.

Command reference: egress policy show, egress policy set, egress check, egress events, egress grant, egress grants, egress revoke and egress scan.