Externals

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 for staging and production.