The first time you deploy an AI agent inside a corporate network and it just... sits there. No connection refused, no timeout logged — just silence. The agent can't reach its peers, can't pull tools from the store, can't phone home. You've hit the corporate firewall problem.
It's not a code bug. It's a network architecture mismatch. Your agent assumes a flat internet. The corporation assumes nothing leaves without explicit permission. Here is how to debug this, step by step, without asking IT for firewall rule changes.
Enterprise networks sit behind NAT and enforce egress filtering. Outbound traffic goes through:
Most AI agent communication frameworks assume bidirectional connectivity — they open a listener and wait for peers to connect. Behind a corporate NAT, there is no listener. There is no routable address. The agent has outbound-only access to the internet.
Here is the checklist, in order.
Many corporate firewalls block all UDP outbound — the only protocol they allow is TCP on ports 80, 443, and sometimes 22. This kills most peer-to-peer protocols, which rely on UDP for NAT hole-punching.
timeout 5 bash -c 'echo test > /dev/udp/8.8.8.8/53' && echo "UDP egress OK"
If this hangs or fails, your firewall drops UDP entirely. Take note — this rules out direct STUN-based hole-punching and plain UDP tunnels. You will need either TCP fallback or a relay.
Corporate DNS often resolves internal-only records, blocks external queries, or returns a captive portal. An agent that cannot resolve peer addresses is an agent that cannot connect.
dig +short pilotprotocol.network @8.8.8.8
dig +short pilotprotocol.network
If the public resolver works but the system resolver does not, you have a DNS intercept or split-horizon DNS. The agent should use a public resolver or DoH (DNS over HTTPS) to bypass internal DNS.
Many corporate networks run transparent proxies that intercept TCP/80 and TCP/443 traffic. Your agent's TLS connection terminates at the proxy, not the target server. This breaks certificate pinning, WebSocket upgrade headers, and any protocol that expects raw TCP.
curl -v https://api.github.com 2>&1 | grep -i "proxy\|x-forwarded-for\|via"
If you see Via
or X-Forwarded-For
headers, you are behind a transparent proxy. Your agent needs to either trust the proxy's CA certificate or avoid protocols the proxy intercepts.
Guesswork is expensive. Find out exactly which ports and protocols can reach the outside world:
for port in 80 443 8080 8443 53 123 3478 4433 51820; do
timeout 3 bash -c "echo >/dev/tcp/pilotprotocol.network/$port" 2>/dev/null &&
echo "TCP/$port open" || echo "TCP/$port blocked"
done
Most corporate networks only allow TCP/443 (HTTPS) outbound. Some add TCP/80 for HTTP and TCP/22 for SSH. UDP is typically blocked entirely. If only TCP/443 is open, every protocol your agent uses must tunnel over TLS.
If UDP is open, run a STUN test to understand the NAT type. This tells you whether hole-punching is even possible.
apt-get install -y stun-client
stun-client stun.l.google.com 19302
Results you might see:
This is the reality for most corporate environments. UDP is dropped. Symmetric NAT is the norm. Direct peer-to-peer connectivity is impossible.
You have three options:
Set up a relay server on a VPS with a public IP. The agent opens a long-lived TCP connection to the relay (outbound — no firewall change needed). The relay forwards traffic from peers to the agent.
ssh -R 8080:localhost:3000 user@your-relay-server -N
This works but has downsides: every byte goes through the relay, which becomes a bottleneck and a single point of failure.
Overlay networks run a lightweight client inside the agent's environment. They handle the STUN, NAT traversal, and relay fallback transparently. The agent gets a virtual address that works regardless of the underlying network.
This is where overlay approaches like Pilot Protocol fit — the agent runs a small daemon that establishes outbound connections to the network, negotiates encryption, and keeps a tunnel alive. Peers reach it by its virtual address, and the overlay handles the relay fallback automatically when direct hole-punching fails. The agent never opens an inbound port.
If your agent framework supports WebSocket transport, it can run over TCP/443 as standard HTTPS traffic, which passes through even strict firewalls. This is the simplest workaround if you control both ends.
const ws = new WebSocket("wss://your-relay.example.com/agent");
ws.onmessage = (event) => handleMessage(JSON.parse(event.data));
Whatever relay or overlay you choose, verify your agent can reach it from inside the corporate network:
curl -sI https://your-relay.example.com/health | head -1
Do this from the agent's actual environment, not from your laptop. Corporate networks often whitelist DNS but not arbitrary IPs.
Some corporate proxies require authentication. If your agent's HTTP client doesn't send proxy credentials, requests silently fail or return a captive portal page.
export HTTP_PROXY="http://user:pass@proxy.corp.com:8080"
export HTTPS_PROXY="http://user:pass@proxy.corp.com:8080"
Most HTTP client libraries support these environment variables. Not all UDP-based VPNs or overlay networks do.
If your agent uses mutual TLS, the corporate proxy's certificate interception breaks the handshake. Solutions:
Before you conclude an agent cannot run behind a corporate firewall, verify each of these:
echo test > /dev/udp/8.8.8.8/53
dig pilotprotocol.network @8.8.8.8
curl -v https://api.github.com | grep -i proxy
curl -sI https://relay-host/health
HTTP_PROXY
, HTTPS_PROXY
set?Nine times out of ten, the fix is one of: run the agent's traffic over TCP/443, set up a relay, or install a corporate CA certificate. Overlay networks that handle NAT traversal and relay fallback automatically make this a configuration problem rather than an architecture problem. The agent gets a permanent address, and the overlay decides how to reach it — through a direct hole-punched tunnel when possible, through a relay when not.
The corporate firewall is not the end of the road. It just means your agent needs a network layer that was designed for the network it actually has, not the one you wish it had.