Langy Networking and Egress

The NetworkPolicy and L7 egress adapter that govern what the Langy agent pod can reach, the GitHub FQDN floor, and the cooperative-vs-mandatory enforcement limit.

The Langy agent pod has no outbound HTTPS by default: networkPolicy.allowExternalHttps is false, so a fresh install cannot reach GitHub, npm, or any external host.

To let Langy clone and push (open PRs), you enable egress. The pod’s traffic then passes through an L7 egress adapter that requires TLS, allow-lists destinations, and enforces a GitHub FQDN floor.

LLM traffic never uses this path; it goes to the in-cluster LangWatch AI Gateway.

The one boundary to understand before you rely on this in a regulated environment: once networkPolicy.allowExternalHttps is true, the L7 adapter is cooperative by default. A prompt-injected worker can dial an external IP directly on :443 and bypass it, and that bypass is monitored, not blocked, in the stock pod. Mandatory enforcement is opt-in and needs the Cilium CNI. The details are below and in The sandbox.

Also check: Self-hosting overview, Environment variables, The sandbox.

Why egress is L7, not iptables

By default the pod runs on the node’s normal container runtime (runtimeClassName: ""). gVisor, or another sandboxed RuntimeClass, is an opt-in hardening step, see Setup.

Egress control has to work on both runtimes. gVisor’s network stack supports only part of iptables and nftables, so Langy does not rely on iptables-based controls (REDIRECT, OWNER-match DROP, NAT).

That is why per-worker egress control lives at L7, in a per-worker CONNECT proxy inside the manager, rather than in kernel firewall rules. The same controls apply whether or not you enable the sandbox. See The sandbox.

What the agent needs to reach

Destination	Why	Path
In-cluster LangWatch AI Gateway	All LLM traffic (traced, budgeted, policed)	Always, in-cluster
In-cluster LangWatch app	The langwatch CLI (per-session key)	Always, in-cluster
github.com, api.github.com, codeload.github.com	Clone and push for pull requests	Only when egress is on
api.github.com, or GITHUB_LANGY_HOST when one is set (from the control plane, not the agent pod)	Mint 1-hour installation tokens, read installation metadata, and list pull requests for a branch	Control plane

Private ranges (RFC 1918), CGNAT (100.64.0.0/10), and the cloud metadata service are blocked at L3/L4 regardless of the egress toggle, which is the SSRF and IMDS protection.

With GITHUB_LANGY_HOST set to a GitHub Enterprise Server hostname, the control plane reaches that host instead of api.github.com. Workers keep using the github.com names, because they clone with the gh command line. See GitHub Enterprise Server.

Inbound

Everything above is outbound. The one inbound path GitHub uses is the webhook, delivered to <BASE_URL>/api/v1/github/webhook.

It is optional. An instance GitHub cannot reach still connects and works, and reconciles late instead. For what changes, see Restricted networks.

Local control connections

Local development lets a developer share a folder on their machine with Langy. The langwatch langy --share-control command opens one outbound connection from the developer’s machine to the LangWatch app, not to the agent pod. The agent pod needs no new egress: the worker reaches the app in-cluster, on the path it already uses.

Route	Direction	Purpose
<BASE_URL>/api/v1/langy/control/connect	Developer machine to app, WebSocket upgrade	The live relay for file and command calls
<BASE_URL>/api/v1/langy/control/connect/*	Developer machine to app, HTTPS	Long-poll fallback when the upgrade is refused
<BASE_URL>/api/v1/langy/control/requests	Developer machine to app, HTTPS	List, approve and cancel control requests

An ingress that does not pass WebSocket upgrades still works: the CLI falls back to long-polling on its own. Each poll holds for up to 20 seconds, so keep the ingress read timeout at 30 seconds or more. The same timeout already applies to connected agents.

The developer authenticates with their device session to approve a request, and the CLI then holds a Langy session key scoped to one conversation. The key stops working when the CLI disconnects or the conversation’s workspace is disconnected from the chat.

Push notifications

Langy’s browser notifications are Web Push messages. The LangWatch app and workers send them over HTTPS (:443) straight to the push service of each subscribed browser. The agent pod is not involved, and push needs no configuration: the install generates its own VAPID key pair on first use and stores it encrypted in the database.

Browser	Push service host
Chrome, Edge on Android, Opera, Samsung Internet and other Chromium browsers	fcm.googleapis.com
Firefox	updates.push.services.mozilla.com
Safari on macOS and iOS	web.push.apple.com (Apple documents *.push.apple.com)
Edge on Windows and macOS	*.notify.windows.com

The app refuses a subscription whose endpoint is on any other host. Allow the hosts for the browsers your team uses. When the app cannot reach a push service, the send is retried with backoff for about ten minutes, and then dropped.

A browser that cannot subscribe at all, because it has no Push API or subscribing failed, gets its notifications from the open LangWatch tab instead. A browser that did subscribe never falls back to the tab, so blocking these hosts after people subscribed means their notifications stop.

Enable outbound egress

The stock charts/langyagent chart keeps networkPolicy.allowExternalHttps: false. To allow git, gh, and npm, turn it on in your langwatch chart values:

values.yaml

langyagent:
  networkPolicy:
    allowExternalHttps: true

With it on, the pod may open :443 to anywhere at L3/L4, and the L7 adapter is what narrows that to the allowed destinations. The FQDN floor (github.com, api.github.com, codeload.github.com) works without further changes.

Make sure langyagent.networkPolicy.privateExcept and privateExceptV6 include any non-RFC1918 service or VPC CIDR you actually need to reach. The defaults already include 100.64.0.0/10 (CGNAT) for EKS custom networking.

The L7 egress adapter

When egress is on, each worker’s outbound traffic is forced through a per-worker CONNECT proxy (ADR-076) that applies, in order:

Control	Env var	Default	Effect
Require TLS	LANGY_EGRESS_REQUIRE_TLS	true	Refuse cleartext and non-:443 forwards.
FQDN floor	LANGY_EGRESS_FQDN_FLOOR	github.com,api.github.com,codeload.github.com	Operator always-allowed FQDNs, on top of a project’s own allow-list.
Enforce floor	LANGY_EGRESS_ENFORCE_FLOOR	false	When on, the floor becomes a hard ceiling for projects that have no allow-list of their own. Default is monitor-only.
SNI cross-check	LANGY_EGRESS_SNI_CROSSCHECK	true	Cross-check the TLS SNI against the CONNECT authority to block domain-fronting.

See Environment variables for the full table.

Hardened installs

For a tighter perimeter than “:443 to anywhere, narrowed at L7”, flip allowExternalHttps back to false and add an explicit allow-list of the three GitHub FQDNs at the CNI layer, so the L3/L4 policy itself only permits GitHub:

values.yaml

langyagent:
  networkPolicy:
    allowExternalHttps: false
  egress:
    enforceFloor: true
    cilium:
      enabled: true

An operator can also place the pod on an opt-in public-subnet node group (a node group with no route to the private data tier) via nodeSelector, affinity, and tolerations.

The cooperative-vs-mandatory limit

State this plainly for a regulated review. Today (ADR-053, Proposed):

• Shipped. The L3/L4 NetworkPolicy is deny-by-default: :443 to anywhere is off unless you enable it, and private ranges, CGNAT, and cloud metadata are blocked regardless. The default service-account token is dropped. Node placement on a public subnet with no route to the data tier is available. The L7 adapter’s require-TLS, SNI cross-check, and FQDN floor apply to traffic that goes through the proxy.
• Cooperative, not mandatory. With networkPolicy.allowExternalHttps: true, the L7 egress adapter is cooperative by default. A prompt-injected worker that ignores HTTPS_PROXY can dial an external IP on :443 directly and bypass the adapter. In the stock pod that bypass is monitored, not blocked.
• Opt-in, Cilium only. langyagent.egress.cilium.enabled: true renders a CiliumNetworkPolicy with toFQDNs on the floor, which a worker cannot bypass. It needs the Cilium CNI and is off by default. It enforces the operator floor only; per-project allow-lists stay with the L7 adapter.
• Designed, not shipped. A per-worker network namespace (ADR-033 Fix B, which needs CAP_SYS_ADMIN), the equivalent for clusters without Cilium.

If your threat model requires that a compromised worker cannot reach an arbitrary external host, enable the Cilium toFQDNs path rather than relying on the cooperative adapter alone. See The sandbox for the full boundary map.