Network Outbound Proxy
Relevant source files
The following files were used as context for generating this wiki page:
The Network Outbound Proxy manages all untrusted outbound HTTP traffic from the Coral system. It routes requests through a centralized coral-outbound::Client to ensure that outbound network permissions remain independent of inbound listener selection or identity.
Sources: AGENTS.md:18-22, README.md:33-35
Purpose and Scope
Coral runs agent-written TypeScript programs in a sandboxed environment. These programs have no direct network access. The Outbound Proxy provides a controlled mechanism for the system to reach external services, such as GitHub, Slack, or custom OpenAPI/MCP services, while enforcing operator-defined destination policies.
Sources: README.md:33-35, README.md:55-63, AGENTS.md:18-21
Outbound Architecture
The outbound architecture centers on a destination policy that resolves permissions at bootstrap. The system passes this policy to domain modules, which then utilize the specialized outbound client for all external communication.
Component Interaction
The following diagram illustrates the flow of a request through the outbound proxy system.
The Outbound Proxy enforces boundaries by routing all untrusted traffic through a single point of exit.
Sources: AGENTS.md:18-22, crates/coral-outbound/src/lib.rs
Destination Management
Outbound requests are validated against a Destination which defines the target service. Destinations handle the normalization of URLs and the application of security rules.
URL Normalization and Validation
The proxy ensures that endpoints are absolute HTTP or HTTPS URLs. It rejects components that cannot be safely composed, such as user credentials, query strings, or fragments within the base configuration.
| Rule | Requirement |
|---|---|
| Protocol | Must be HTTPS or explicit-loopback HTTP |
| Format | Absolute URL |
| Forbidden Components | Credentials, Query Strings, Fragments |
Sources: apps/reef/app/lib/coral-endpoint.server.test.ts:16-86, crates/coral-outbound/src/destination.rs
Loopback Policy
Coral treats loopback addresses (127.0.0.1, [::1]) as trusted endpoints for internal communication (e.g., between Reef and the Coral gRPC server). However, it distinguishes between explicit loopback IPs and subdomains like coral.localhost, the latter of which may be rejected depending on the security context.
Sources: apps/reef/app/lib/coral-endpoint.server.test.ts:33-60, apps/reef/README.md:50-60
Transport and Protocol Implementation
The coral-outbound crate implements the underlying transport logic, typically leveraging reqwest or similar libraries for executing the actual network calls.
Sequence of an Outbound Call
The sequence below describes how a domain module initiates a network request through the proxy.
Security Configuration
The outbound proxy is configured via environment variables and the config.toml file. This configuration defines which destinations are allowed and how TLS is handled.
Insecure Endpoint Opt-in
In specific environments where TLS cannot be terminated at the destination, an operator can opt-in to insecure outbound traffic. Setting CORAL_WEB_ALLOW_INSECURE_CORAL_ENDPOINT=true allows the system to send bearer tokens in cleartext over the network, though this triggers a system-wide warning.
Sources: apps/reef/app/lib/coral-endpoint.server.test.ts:40-47, apps/reef/README.md:61-65
Host Identity
The proxy uses CORAL_WEB_PUBLIC_URL as the primary identity for web-based outbound interactions. This URL is used to derive OAuth resources, client IDs, and callbacks, ensuring that the identity used for outbound requests is pinned to the configured public origin.
Sources: apps/reef/README.md:30-45
Conclusion
The Network Outbound Proxy serves as a critical security boundary within Coral. By centralizing all outbound HTTP traffic and enforcing strict destination policies, it ensures that sandboxed agent programs can interact with external services without compromising system credentials or network integrity.