Outbound Egress

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Runtime outbound HTTP and provider calls are governed at the runtime boundary. The egress filters reject unsafe destinations and response URLs, and audit events carry bounded correlation identifiers rather than raw payloads.

Egress governance applies to plugin HTTP clients, web fetch-style tools, SMTP host checks, MCP discovery, and provider response URLs. It is designed to stop SSRF, DNS rebinding, metadata endpoint access, and accidental leakage of credential-bearing URLs into logs.

ORQESTRA_ALLOWED_ACTION_HOSTS is the primary runtime allowlist for outbound plugin HTTP calls. When a local or internal service intentionally resolves to an RFC1918 private IPv4 address, add that hostname to ORQESTRA_PRIVATE_ACTION_HOSTS as well. Keep the private-host list as a subset of the action-host allowlist. Metadata, loopback, link-local, reserved, multicast, unspecified, and private IPv6 destinations are still blocked.

This global ORQESTRA_ALLOWED_ACTION_HOSTS list governs the native workload path (plugin calls inside an Orqestra-run flow). External-runtime mediated tool calls are governed instead by the per-profile egress allowlist carried in the capability token — the certified adapter_artifact.egress_allowlist the control-plane copies into the signed egress_allowlist claim at mint, which the gateway enforces as the mediated tool’s allowed_action_hosts. A networked mediated tool reaching an off-list host fails closed; the global setting does not widen (or veto) a governance-certified profile’s egress bound. The SSRF floor (metadata/loopback/private destinations blocked) applies to both paths.

Configuration

Example:

export ORQESTRA_ALLOWED_ACTION_HOSTS="api.stripe.com,hooks.slack.com,internal-api.example.com"
export ORQESTRA_PRIVATE_ACTION_HOSTS="internal-api.example.com"

Do not allowlist raw metadata IPs, loopback, link-local, or broad wildcard-style hostnames. The guard still blocks metadata and unsafe address classes even when they appear in an allowlist.

SNS and S3 SDK destinations are deployment authority, not workflow inputs. The runtime rejects caller-supplied region, endpoint_url, and region_name values, validates the configured destination before creating an SDK client, and fails closed when the corresponding deployment setting is absent. Configure the three plugin settings in the runtime-gateway API and executor environment, and include their exact hostnames in the applicable action allowlist. S3 also supports deployment-owned S3-compatible endpoints after the shared URL guard, exact host allowlist, SSRF, and DNS-host preflights. Botocore still owns the later socket connection and cannot reuse Orqestra’s DNS-pinned HTTP transport, so SDK socket pinning remains an outbound-proxy follow-up. SNS binds the checked regional endpoint explicitly to its SDK client.

Enforcement Layers

Response Budgets

Runtime egress responses are read through immutable, code-owned profiles. Each profile limits both encoded wire bytes and decoded body bytes before JSON, text, or protocol parsing. A caller-provided max_response_bytes can only lower the selected profile ceiling; it cannot replace the registry profile or raise its limits. Unknown encodings, stacked encodings, invalid declarations, wire overflow, decoded overflow, and cancellation fail closed with value-free errors.

Manually handled redirects are checked against the allowlist and SSRF policy, then their response streams are closed without reading or materializing the redirect body. The next Location is checked again before a request is made. Only the final application response is exposed to the caller.

follow_redirects=True is rejected at the shared client before HTTPX is invoked. Runtime callers must make each hop with follow_redirects=False and discard_redirect_body=True, so every target and response remains under the same guard.

MCP tools/resources discovery also enforces the frozen shape limits: names are at most 128 UTF-8 bytes, descriptions 4 KiB, and each input schema or metadata item 64 KiB. Each list has at most 256 items; the complete list may use the mcp_catalog response profile (512 KiB encoded wire / 1 MiB decoded aggregate). The complete response is validated before projection; one malformed item rejects the response rather than accepting a prefix.

Portal API proxy logs intentionally avoid full upstream URLs. Logs include the incoming path and the upstream path only; query parameters are forwarded to the control plane but are not written to structured logs.

Correlation Fields

Use these bounded IDs for cross-service joins:

• x-request-id
• traceparent
• x-orqestra-workspace-id
• x-orqestra-workload-id
• x-orqestra-execution-id
• x-orqestra-release-id

Audit Event

Outbound HTTP decisions are recorded as v1.infrastructure.egress_http_request. The event is intentionally bounded: operators can join it to execution, workload, workspace, and release context without exposing request bodies, secret values, or full URLs.

Common outcomes include:

Provider Accounting

Provider calls route through governed provider transport. If provider usage has already been burned and a response URL is blocked after the provider returns, runtime-gateway commits burned usage instead of releasing the reservation. This keeps TPM and cost accounting aligned with provider-side spend.

Operator Workflow

When a tenant reports blocked outbound access:

1. Check control-plane governance events for v1.infrastructure.egress_http_request with the workload or execution ID.
2. Confirm the event outcome and bounded reason.
3. Review the workload’s allowed host policy and release binding.
4. Add or update the allowlist only through the governed release path.
5. Re-run the affected workflow and verify a new allowed egress event appears.

Use the resilience runbook for incident triage: docs/resilience/outbound-egress-runbook.md.

Troubleshooting