# Externals

The egress allowlist: the third-party hosts each service and build may reach.

```yaml
externals:
  openai: { hosts: [api.openai.com] }
  prisma: { hosts: [binaries.prisma.sh] }

services:
  web:
    build: { context: ., externals: [prisma] }   # the build may download Prisma's engines
    externals: [openai]                          # the running app may call OpenAI
```

`externals` defines each host once, by name. A service lists the externals its running app (and its jobs) may reach in `externals`, and its build lists its own in `build.externals`. A build reaches only what it lists. At run time, every service and job of a sandbox may reach any external that one of its services lists. Both are limited to ports 443 and 80. Every other outbound call is blocked and listed under `egress.blocked` in the sandbox's status.

- An external that no service or build lists is an error, and so is a name that isn't defined.

- **`hosts`** are exact public DNS names, or `*.example.com` for any name under `example.com` (not `example.com` itself). No other wildcards, and a wildcard can't cover a public suffix such as `*.co.uk`.
- **The allowlist comes from the promoted manifest.** That is the default branch's `parity.yaml` after each merge (unless it is invalid or production is frozen), or a manifest a person promotes with `parity promote`. A sandbox only gets the hosts that baseline also allows. A branch that adds a host keeps it blocked, and the sandbox lists it under `egress.notApproved`. An agent's `parity up` with a sandbox token that adds a host is refused with `egress_not_approved`. To allow a new host, change `externals` in a pull request; merging it updates the allowlist.
- **Credentials.** Vendor keys go in `{ secret: <ref> }` variables, read from the secret store in staging and production. Sandboxes never receive them, so run vendor features that need a live key switched off in sandboxes, or point them at the vendor's test mode with a test key set as a literal `env` value, overridden in [`environments`](/manifest/environments) for staging and production.