---
title: "Egress and credentials"
description: "An allowlist for the hosts native CI and agent sandboxes may reach, and per-task credential grants whose value is attached by the egress proxy and never shown to the agent, a log or the workspace."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```sh
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](/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](/cli/egress-policy-show/), [egress policy set](/cli/egress-policy-set/), [egress check](/cli/egress-check/), [egress events](/cli/egress-events/), [egress grant](/cli/egress-grant/), [egress grants](/cli/egress-grants/), [egress revoke](/cli/egress-revoke/) and [egress scan](/cli/egress-scan/).

Source: https://docs.overlane.app/control-plane/egress/index.mdx