docs/proxy.md
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.
Enable proxy networking for a single build with buildctl build:
buildctl build --proxy-network ...
Enable proxy networking by default in buildkitd.toml:
proxyNetwork = true
Or enable it with the daemon flag:
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.
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:
RUN wget -O- https://example.com/
A step that needs to access a service on the buildkitd host network must
request host networking:
RUN --network=host wget -O- http://127.0.0.1:8080/
The build also needs the host network entitlement:
buildkitd --proxy-network --allow-insecure-entitlement network.host
buildctl build --proxy-network --allow network.host ...
RUN --network=none remains fully offline:
RUN --network=none wget -O- https://example.com/
For proxied execs, BuildKit injects proxy environment variables into the exec process:
HTTP_PROXY
HTTPS_PROXY
http_proxy
https_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.
The proxy records network requests made by exec steps. Build output includes a summary like:
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.
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.
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 HTTP_PROXY and HTTPS_PROXY, use custom trust
stores, or open raw TCP connections cannot bypass the proxy. That traffic is
blocked instead of being captured.