# Build proxy network BuildKit can run exec network traffic through a BuildKit-owned HTTP(S) proxy. The proxy network is controlled by solve or daemon configuration. Once proxy is enabled for a build, BuildKit applies it to every exec that has network access. The exec network mode controls how the proxy itself reaches the network. ## Enabling proxy networking Enable proxy networking for a single build with `buildctl build`: ```bash buildctl build --proxy-network ... ``` Enable proxy networking by default in `buildkitd.toml`: ```toml proxyNetwork = true ``` Or enable it with the daemon flag: ```bash buildkitd --proxy-network ``` The per-build setting and the daemon setting both enable the same runtime proxy behavior. Frontends do not set proxy networking per operation. ## Network mode behavior The exec network mode describes the network access requested by the build step. With proxy networking enabled, BuildKit uses that mode to choose the proxy egress path. | Exec network mode | Proxy behavior | | --- | --- | | default sandbox | Proxy is injected. The proxy reaches the network through a bridge/CNI-style namespace, not through the `buildkitd` host namespace. This is intended for normal internet access and does not expose host loopback services. | | host | Proxy is injected. The proxy reaches the network from the `buildkitd` host namespace. This requires the normal `network.host` entitlement on both the daemon and solve request. | | none | Proxy is not injected. The exec has no network access. | For example, a Dockerfile step using the default network can fetch external URLs through the proxy: ```dockerfile RUN wget -O- https://example.com/ ``` A step that needs to access a service on the `buildkitd` host network must request host networking: ```dockerfile RUN --network=host wget -O- http://127.0.0.1:8080/ ``` The build also needs the host network entitlement: ```bash buildkitd --proxy-network --allow-insecure-entitlement network.host buildctl build --proxy-network --allow network.host ... ``` `RUN --network=none` remains fully offline: ```dockerfile RUN --network=none wget -O- https://example.com/ ``` ## What BuildKit injects For proxied execs, BuildKit injects proxy environment variables into the exec process: ```text HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy NO_PROXY no_proxy ``` `NO_PROXY` includes local loopback names and addresses, so direct localhost traffic from the process is not sent through the proxy by default. If the process clears `NO_PROXY`, localhost requests are sent to the proxy and then handled according to the exec network mode. BuildKit also injects a generated CA certificate into common Linux trust bundle locations for the duration of the exec. This lets HTTPS requests using the system trust store pass through the BuildKit proxy. ## Upstream proxies To use an upstream proxy, set `HTTP_PROXY` and/or `HTTPS_PROXY` in the `buildkitd` environment and enable proxy networking: ```bash HTTP_PROXY=http://proxy.example:3128 \ HTTPS_PROXY=http://proxy.example:3128 \ NO_PROXY=localhost,127.0.0.1,.example.internal \ buildkitd --proxy-network ``` BuildKit uses Go's standard proxy environment handling: | Variable pair | Purpose | | --- | --- | | `HTTP_PROXY`, `http_proxy` | Selects the upstream proxy for HTTP destinations. | | `HTTPS_PROXY`, `https_proxy` | Selects the upstream proxy for HTTPS destinations. | | `NO_PROXY`, `no_proxy` | Lists destinations that bypass the upstream proxy. | For each pair, BuildKit uses the uppercase variable when it is non-empty and falls back to the lowercase variable. The HTTP and HTTPS settings are independent: `HTTP_PROXY` and `http_proxy` do not apply to HTTPS destinations. BuildKit injects `ALL_PROXY` and `all_proxy` into proxy-network execs. It does not read these variables from the `buildkitd` environment when it configures upstream routing. Proxy values can be complete `http://`, `https://`, `socks5://`, or `socks5h://` URLs. A bare `host[:port]` uses HTTP. `NO_PROXY` is a comma-separated list of domain names, IP addresses, and CIDR prefixes. Domain names and IP addresses can include a port. When a destination matches the list, BuildKit's proxy connects to it directly. A value of `*` makes direct connections to all destinations. `NO_PROXY` controls how the BuildKit proxy reaches the destination. It does not change the proxy variables in the exec. These settings apply to all proxy-network execs. Proxy settings passed to an individual exec do not change upstream routing because its proxy variables point to BuildKit's internal proxy. If an upstream proxy URL is invalid, the proxy-network exec fails to start instead of connecting directly. ## Request capture and logs The proxy records network requests made by exec steps. Build output includes a summary like: ```text proxy network requests: - GET https://example.com/ -> 200 - GET http://127.0.0.1:8080/ -> 502 ``` Successful GET responses can be captured as build materials. When provenance is requested, these captured materials are added to the provenance dependency list with proxy network metadata. If a GET request cannot be captured completely, BuildKit can report it as an incomplete proxy material in provenance metadata. ## Source policy Proxy requests use BuildKit source policy checks. The proxy evaluates proxy-visible HTTP(S) requests as synthesized HTTP source ops, so policy can be used to allow, deny, or convert matching proxy GET URLs. Conversion currently applies to GET requests where only the URL is changed. This keeps proxy network access aligned with the same policy model used for other BuildKit sources. ## Scope and limitations The proxy network feature currently applies to exec traffic. It does not replace image resolver, Git, HTTP source, or other non-exec fetch paths. The current implementation is Linux-focused. Rootless workers also have the usual rootless networking limitations, where worker networking may behave like host networking. Applications that ignore the injected proxy environment variables, use custom trust stores, or open raw TCP connections cannot bypass the proxy. That traffic is blocked instead of being captured.