Binding & network exposure

Paddock runs commands, holds your tokens, and can read and write your repositories. Where it listens is therefore a security decision, not a convenience one — so since v0.44 the defaults treat it that way.

The default bind host changed from 0.0.0.0 (all interfaces) to 127.0.0.1 (loopback only).

If you run Paddock from source or the release tarball and reached it from another machine without ever setting HOST, upgrading to v0.44 or later will make it stop answering — connections from anywhere but the box itself are refused. Nothing is broken; it is bound where you didn’t ask it to be reachable.

The fix is one variable, plus a decision about auth — see I upgraded and now I can’t reach it below.

The changed default doesn’t reach you if you run a container image — those still bind 0.0.0.0 deliberately — but the fail-closed guard below applies to containers just the same, and they need a flag of their own to boot at all. See Containers. You’re unaffected either way if you already set HOST / PADDOCK_HOST explicitly; only the default changed.

The two rules

1. The default is loopback

HOST defaults to 127.0.0.1. A fresh git clone or tarball run is network-closed: reachable from the box itself, from nothing else. You opt in to more.

Resolution order, highest first:

HOST
PADDOCK_HOST (an alias — HOST wins if both are set)
host: in paddock.config.yaml
127.0.0.1

2. Exposed and unauthenticated refuses to start

Binding a non-loopback address while PADDOCK_AUTH_MODE=none is the actual footgun, and Paddock will not do it. Startup fails closed with a message naming your options — the same fail-closed treatment as jwt mode without a JWKS URL.

Bind host	Auth mode	Result
Loopback	anything	✅ Starts
Non-loopback	`trusted-header` or `jwt`	✅ Starts — no flag needed (but see the caution below: the guard checks only that a mode is set)
Non-loopback	`none`	❌ Refuses to start
Non-loopback	`none`, with `PADDOCK_DANGEROUSLY_ALLOW_OPEN`	⚠️ Starts, logs a loud warning

Note the second row: binding widely is fine once you have real authentication. The guard isn’t about exposure alone, it’s about exposure without a way to tell who’s knocking.

evaluateBindSafety asks one question: is PADDOCK_AUTH_MODE something other than none? It cannot tell a mode that proves identity from one that merely reads it. So trusted-header on 0.0.0.0 starts silently, with no warning, and in that mode anything that can reach the port can forge the identity header — including anything that reaches it around your proxy.

That is only safe when something outside Paddock guarantees the proxy is the sole route to the port: a private container/pod network, a firewall rule, a VPN interface. Binding 0.0.0.0 is precisely the case where that guarantee is easiest to lose — the port is now open on every interface, and the proxy is one of the things that can reach it, not the only one.

jwt is the mode that is spoof-proof on its own, because Paddock verifies the token’s signature itself and a request arriving directly is still rejected. If the network boundary is doing the work instead, keep the bind narrow (loopback, or the one private interface the proxy is on) rather than widening it and relying on the mode. See Authentication for the comparison.

What counts as loopback

localhost, the whole IPv4 127.0.0.0/8 range, the IPv6 loopback ::1, and IPv4-mapped loopback like ::ffff:127.0.0.1. Bracketed forms ([::1]), surrounding whitespace and casing are all normalised first.

0.0.0.0 and :: are not loopback. They mean every interface, which is exactly the case the guard exists for.

I upgraded and now I can’t reach it

Pick whichever of these matches what you actually want:

Put authentication in front of it (the right answer). Set an auth mode and bind wide. Nothing else is needed — no dangerous flag, no warning.

HOST=0.0.0.0
PADDOCK_AUTH_MODE=trusted-header   # behind a proxy that authenticates

With trusted-header, “the right answer” carries a condition: the network must guarantee that proxy is the only route to the port, because the header is forgeable by anything that can reach it — see the caution above. jwt needs no such condition.

See Securing Paddock for the ladder from a VPN through to SSO.

Keep it on loopback and reach it through a proxy on the same box. A reverse proxy (Caddy, nginx, Traefik) listening publicly and forwarding to 127.0.0.1:4000 is a very good posture: only the proxy is exposed, and it’s the thing doing TLS and auth. Nothing to change — this is the default.

Reach it over a VPN or overlay network. Bind loopback (or the tailnet interface) and let WireGuard / Tailscale be the network boundary.

You genuinely want an open, unauthenticated server. Then say so out loud:

HOST=0.0.0.0
PADDOCK_AUTH_MODE=none
PADDOCK_DANGEROUSLY_ALLOW_OPEN=1

It boots, and logs a warning on every start telling you that anyone who can reach the port can run code and spend your Claude tokens as you. The variable is named the way it is on purpose. Accepts 1 / true / yes.

Containers are different

The published images still set HOST=0.0.0.0, and that’s correct — not an oversight.

Inside a container the network namespace is the isolation boundary. Docker cannot reach 127.0.0.1 inside the container, so a loopback bind there would make the app unreachable even from a deliberately-published port. The app also can’t see the host’s publish posture from inside, so it’s in no position to police it.

The safe posture for a container is therefore carried by how you publish the port, not by the bind host:

The guard is not skipped for containers. Nothing in Paddock detects that it’s running in one: evaluateBindSafety runs unconditionally at startup and a refusal throws. So the image’s HOST=0.0.0.0, plus the default PADDOCK_AUTH_MODE=none, plus no override is exactly the refuse case — a plain docker run ghcr.io/edspencer/paddock:latest exits immediately:

refusing to start: bind host "0.0.0.0" is not loopback and PADDOCK_AUTH_MODE=none, …

Every container run therefore needs either a real auth mode or PADDOCK_DANGEROUSLY_ALLOW_OPEN=1. The latter is the right answer only when the publish is loopback-bound, as below — it tells the app “I know the bind looks open; the namespace and the publish are my boundary.”

# reachable only from the host, not the LAN
docker run -p 127.0.0.1:4000:4000 \
  -e PADDOCK_DANGEROUSLY_ALLOW_OPEN=1 \
  ghcr.io/edspencer/paddock:latest

The paddock-deploy recipes already do both — the loopback publish and the override, with the reasoning inline. The distinction that matters is which mechanism protects you: on bare metal, tarball, VM and systemd-in-LXC runs it’s the bind host; in a container it’s the publish posture, and the flag is how you tell the app so.