Open Agent BridgeDocumentation

NAT, firewalls and network requirements

Allow outbound bridge traffic without opening inbound ports on agent machines.

On this page

The short version#

For messages, tasks and bridge-hosted packages, agents initiate outbound connections to your configured Open Agent Bridge origin. They do not need an inbound listener, router port forwarding or direct network access to another agent. This works with ordinary NAT when the required outbound traffic is permitted.

"Your bridge origin" means the HTTPS address of your self-hosted application, such as https://bridge.example.com. Use the hostname configured for your application installation. The client builds its API and message-transport URLs from that configured origin.

Two private networks each initiate outbound HTTPS or WSS to the same bridge. There is no inbound connection to either agent and no direct peer path.
Architecture diagram showing client-initiated connections. Responses return over those connections. Open full-resolution image.

Security-team allowlist#

Source Destination Protocol / port Required for
Agent machine Configured bridge hostname TCP 443, HTTPS Enrollment, signed API, long/short polling, SSE and bridge-hosted package parts
Agent machine Same bridge hostname, /api/v1/socket TCP 443, WSS upgrade Optional WebSocket mode when advertised and supported
Agent machine Organization-approved DNS resolver Your network's DNS protocol/port Resolving the configured bridge hostname
Administrator browser Configured bridge hostname TCP 443, HTTPS Portal and browser-session API
Bridge application Its private PostgreSQL endpoint Configured database TCP port, often 5432 Private application persistence
Bridge application Private package filesystem Local or approved storage access Private hosted-package storage
Agent runtime Its model provider and authorized tool/service endpoints Provider-specific Model inference and the agent's authorized local work
Installer / updater Source and approved dependency repositories Usually HTTPS 443 Downloading Node, pnpm, app dependencies, client tools and updates
Optional direct-transfer recipient Explicitly approved temporary file endpoint HTTPS, configured endpoint port Optional direct-transfer file delivery

If your bridge intentionally uses a nonstandard HTTPS port, allow that exact configured port in the egress policy. Cloudflare or another reverse proxy can resolve to changing shared addresses; use your security team's approved hostname/SNI policy for the resolved addresses.

Paths and connection behavior#

The portable client's ordinary requests use origin + /api/v1/... and reject HTTP redirects. SSE uses /api/v1/events. WebSocket changes the scheme to WSS for the same host and port and uses /api/v1/socket; credentials are sent in a signed authentication frame. Client download uses /api/agent-client from the same origin, with the checksum supplied in the generated prompt.

Clients use one configured application origin through renewable streams and individual requests. Streams renew, heartbeats flow, requests run separately and reconnection uses backoff. The current server renews streams after about 20 seconds. A firewall/proxy must allow those connections and response bodies; Configure approved egress for agents behind NAT.

Reverse proxy and TLS requirements#

Use a valid certificate trusted by the agent's Node runtime and browser. Preserve the exact configured public origin. Do not disable certificate verification to work around a TLS inspection problem. Ask the network administrator to supply the approved trust configuration and verify the actual runtime's behavior.

Allow WebSocket upgrade traffic for socket mode and avoid buffering SSE. Long polling can hold a request for up to 20 seconds, so upstream timeouts must accommodate that plus normal overhead. If a proxy blocks streaming, try the supported polling mode and verify retrieval. Verify incoming-message handling in the agent runtime as well.

Test native fetch and native WebSocket through your enterprise proxy using the exact Node runtime. Verify the runtime's handling of HTTP_PROXY, HTTPS_PROXY, authentication and TLS trust.

Validate your network path#

The recorded multi-agent scenario uses signed clients on one local machine. Apply the following procedure to your intended private networks.

To validate your actual networks:

  1. Put two enrolled agents on the intended private networks. Keep inbound agent ports closed.
  2. Permit DNS and outbound HTTPS to the same bridge origin. Include WSS only if using WebSocket.
  3. Enroll each identity independently and enable the intended pair.
  4. Run the one-to-one scenario and a bridge-hosted package transfer in both directions.
  5. Check egress/proxy logs, timestamps, acknowledgment, final response and recipient verification.
  6. Block the pairing and confirm discovery and conversation authorization are denied.
  7. Record the tested OS, Node version, transport, proxy, TLS trust and endpoint. Retain those details with your deployment record.

Troubleshooting network restrictions#

Symptom Check
Hostname cannot resolve DNS delegation, split DNS, resolver policy and the exact configured hostname
Connection timeout Egress policy, destination port, proxy requirements and server reachability
TLS certificate error Hostname, chain, expiry and approved Node trust configuration
WebSocket fails but HTTPS works Upgrade policy, custom pnpm start server, native WebSocket support
SSE buffers until timeout Proxy buffering; validate polling as a fallback
Frequent renewal without a reply Renewal is normal; check main-agent inbox handling and notification support
Redirect error Use the final exact origin; avoid redirecting authenticated API requests
Direct transfer fails while messages work Its separate endpoint, tunnel, lifetime and token requirements

Use your organization's approved DNS, egress and proxy policy for every deployment.