Network
Limit what a container task or service reaches: only the services it needs, a list of hosts and ports through an egress proxy, or everything.
A container task reaches whatever the machine it runs on reaches. That is fine for
most builds, but not for a step that should not need the network (a test suite), or
for code you don't fully trust (an install script, an agent's change). network
limits what a task or service reaches besides the services it needs.
tasks:
test:
image: node:24-alpine
network: none # nothing at all
cmds: [npm test]
e2e:
image: node:24-alpine
needs: [postgres]
network: none # postgres, and nothing else
cmds: [npm run e2e]
install:
image: node:24-alpine
network:
allow: [registry.npmjs.org, '*.githubusercontent.com']
cmds: [npm ci]
migrate:
image: node:24-alpine
network:
allow: ['db.example.com:5432'] # raw TCP to one host and port
cmds: [npm run migrate]
deploy:
image: node:24-alpine
network: open # the default
cmds: [npm run deploy]
services:
postgres:
image: postgres:16-alpine
healthcheck:
cmd: pg_isready -U postgres| Level | Reaches, besides its needs |
|---|---|
open (default) | Everything the host reaches, as without network. |
none | Nothing. |
allow: [hosts] | HTTP and HTTPS to the listed hosts, and raw TCP to a listed host and port, through an egress proxy. |
The services in needs are reachable at every level, under the names the task
needs them by: a task lists a service because it uses it. Under a limit, those
names must be host names (db, api-v2), never patterns: the egress proxy passes
a needed service by exactly its name. network works the same
on container services, and the tasks and
services that need a limited service still reach it.
network is not part of the cache key: it decides whether a
task can work, not what a successful one produces. Ports a service publishes on the
host stay published.
A limit holds or the run fails: where hammerkit can't make it hold (an older Docker, Windows containers, a cluster that doesn't enforce NetworkPolicy), a task or service with a limited network is an error before it starts, never a run without limits.
Allowed hosts
A host is a name (registry.npmjs.org) or *. and a domain for every name under
it (*.githubusercontent.com allows raw.githubusercontent.com, not
githubusercontent.com itself). Names only, no IP addresses (nor names a resolver
reads as one, such as 0x7f000001 or 127.1), and any port of an allowed host is
allowed through the proxy. A name with a port (db.example.com:5432) is a
TCP forward.
The proxy resolves an allowed name itself and connects to the address it checked. A
name a wildcard allows must not resolve to the host, a private network or the
cluster (loopback, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and the like), so
a domain whose DNS someone else controls can't point into your network; a name you
list exactly may. No name may resolve to a link-local address, where cloud metadata
services live.
Under allow, hammerkit starts an egress proxy next to the task and sets
HTTP_PROXY, HTTPS_PROXY and NO_PROXY (and their lowercase spellings) for it,
with the needed services in NO_PROXY. Package managers, curl, git and most
HTTP clients read these variables; Node's built-in fetch only with NODE_USE_ENV_PROXY=1
(Node 22.21 and 24.5 on). The proxy passes requests and CONNECT tunnels
to an allowed host and answers everything else with 403 Forbidden. Each refused
host shows up once in the task's log, so a failing install says why:
warn network: refused example.comThe proxy is the only way out. A tool that ignores the proxy variables finds no
route at all, and it fails closed: when the proxy is gone, nothing gets out. A tool
that ignores NO_PROXY (busybox wget, say) still reaches the needed services,
through the proxy. BusyBox wget, the wget of Alpine images, also asks the proxy
for an https:// URL instead of opening a CONNECT tunnel; TLS stays between the
client and the host, so the proxy doesn't serve that, and the log says so: use
curl or GNU wget (apk add wget) for an https host. A service's healthcheck
checks the service itself, so it runs without the proxy variables.
TCP forwards
Databases, caches and most other clients that don't speak HTTP ignore the proxy variables, so they can't use an allowed host. For them, an entry names a host and a port:
tasks:
migrate:
image: node:24-alpine
network:
allow: ['db.example.com:5432', 'cache.example.com:6379']
cmds: [npm run migrate]The proxy listens on that port and forwards each connection, as raw TCP, to that
port of that host, and the task reaches the proxy under the host's own name: psql -h db.example.com connects as it would without a limit, and TLS stays between the
client and the host. The proxy resolves the name itself and checks every address,
as for a name listed exactly. Nothing else of that host is reachable without the
proxy variables; with them, a CONNECT to that host and port passes too. A
connection to another port of that name finds nothing listening and is refused
right away, so it doesn't show up among the refused hosts in the log.
A forward names one host, never a *. pattern, and two hosts can't share a port in
one allow list, since the proxy listens on it for one of them. Port 3128 is the
proxy's own, and a forward can't use the name of a service the task needs. A
database the task runs itself still belongs in its needs as a
service: those are reached directly, on any port.
On a server, a host or forward with a private
address (10.x, 192.168.x and the like) is reachable only when the operator lists it in
allowedEgress, or in the firewall of a Docker host: the server keeps its runs off the
networks behind it unless told otherwise.
A ceiling for the run
--network on run and up sets the most any
task or service of the run reaches, whatever the build file says. It is how a run
of code you didn't write gets limited without changing the build file:
hammerkit run test --network none
hammerkit run install --network allow:registry.npmjs.org,*.npmjs.com
hammerkit run migrate --network allow:db.example.com:5432The levels are ordered none < allow < open, and the ceiling clamps a more open
setting down to it: under --network none every task reaches its needed services
and nothing else. Under an allow: ceiling, an open task gets the ceiling's
hosts, and a task with its own allow list keeps the hosts both lists allow. A host
without a port allows its forwards (db.example.com and *.example.com both keep
db.example.com:5432), while a forward only allows itself. A name that one of the
two lists allows only through a pattern counts as a pattern: under *.example.com,
the task's db.example.com:5432 must not resolve to a private address. Two forwards
on one port, one from each list, are an error. A service started by an earlier up
is recreated when the ceiling changes its network.
A server sets the same ceiling for all of its runs
with runs.network, and refuses to publish a build file that asks for more. With
runs.secretNetwork it sets a lower one
for the tasks that read secrets.
Local tasks
Hammerkit can't limit the network of a local task (one without an image), which
runs on the host. network other than open on a local task is an error
when the build file is read, and so is a --network ceiling below open with a
local task in the run. Run the task in a container to limit it. On a
server with a Kubernetes backend a local task runs in a
pod of a tool image, and there it may be limited.
Docker
Limits need Linux containers on Docker 28 or later. A limited task or service gets
an internal Docker network of its own, with no route out and no address on the
host (com.docker.network.bridge.inhibit_ipv4), so it doesn't reach the host's own
services either. The first service it needs joins that network under the name it needs
it by; each further one gets an internal network of its own that only the task or service
(and its proxy) joins, so the services it needs don't reach each other through it. A task
with network: none that needs no service gets no network at all, only the loopback
interface.
Each of these networks takes an address range of the Docker daemon, whose default pools hold
about 30. A host that runs many limited tasks with several needs at once can run out of them;
smaller default-address-pools (such as /24s) in the daemon's daemon.json make room for
more, and the error says so.
The container that copies a task's or service's outputs into and out of its volumes for the
cache runs its image, so it has no network at all, whatever the
task's network.
Under allow, the task or service and its proxy share a second internal network
that nothing else joins, and the proxy listens there only: the services it needs
can't use its allow list. The host of each TCP forward is an entry in the
container's /etc/hosts that points at the proxy there. The proxy is also on the default bridge, to reach the
allowed hosts. It is a small Node.js script run in a stock node:24-alpine
container, pinned by digest, so there is no hammerkit image to pull; it runs
unprivileged, on a read-only root.
A limited service's ports are published by a relay container next to it, which passes each connection on to the service; the service itself stays without a route out.
The networks, proxy and relay are removed with the task or service: a service
started with up --daemon keeps them until down, and clean
removes those of a run that was killed. Their names carry the run, so two runs of
the same task never share them.
Kubernetes
On a Kubernetes environment, a limited task's jobs and a
limited service's pods get a NetworkPolicy that allows egress to the pods of the
services they need and, under allow, to their proxy, which runs as its own
Deployment and Service, with a port for each TCP forward. Everything else is denied, DNS included: the needed
services, the proxy and the hosts of TCP forwards are host aliases of the pod. The policy limits ingress too:
a task takes no connections, a service takes them from the tasks and services that
need it, and from anywhere when one of the environment's httpRoutes points at it.
The proxy takes connections from its own task's or service's pods only. A service's
healthcheck probe runs through env to empty the proxy variables, so its image
needs an env binary.
A NetworkPolicy only takes effect when the cluster's network plugin enforces it
(Calico, Cilium, and recent versions of kind's kindnet do; some plain setups
don't), and hammerkit can't tell from the API. So the environment states it:
environments:
cluster:
kubernetes:
context: ci
networkPolicy: enforcedWithout it, a task or service with a limited network is an error.
Some plugins, kindnet among them, apply a policy a moment after a pod started. So a
limited pod starts with an init container, hammerkit-network, that waits until the
pod no longer reaches the cluster DNS, which its policy denies; the task's or
service's own containers start after it. When the policy doesn't take hold within a
minute, the pod fails rather than run without limits. The init container runs from
the proxy's image. On a server, a pod with an open
network is limited too, by the policies of its namespace, and has the same init container
when the server states networkPolicy: enforced: it waits until the pod no longer reaches
the clouds' metadata endpoint, 169.254.169.254, which those policies deny by default. On a
cluster where that address doesn't answer, it opens at once; the server's openNetworkGate
points it at another denied address or turns it off (see
Namespaces).
The pod that copies files into and out of a task's or service's volume claims mounts its outputs where the task wrote them, so it runs nothing from its image's paths: an init container copies a pinned, static busybox into a folder of its own, mounted read-only, and every command runs that busybox. No output may be in or over that folder. On a server, that pod has no network at all: the policies of its task or service leave it out.
A task's policy and proxy belong to its run, so concurrent runs of the same task
keep their own. They are removed only once the run's pods have ended, so a
cancelled or timed-out job doesn't keep running without limits while it
terminates. A task's refused hosts show up in its log; a service outlives the run on
a cluster, so its refused hosts are in the log of its proxy, the Deployment named
hammerkit-proxy-<id>.