architecture/port-allocations.md

Port allocations for internal services

Extends generic.md §9 (firewalld) and §3 (Binaries and Runtime). Every service that listens on a TCP port needs a port number, and on a fleet where many services share hosts — and where a runner, a proxy, and an app can land on the same box — a careless choice collides. This doc is how we pick numbers that don't, and the registry of what's already assigned.

Decision rule (the whole thing in one line):

Pick an uncommon port in the IANA registered range (1024–49151), never a crowded alt-HTTP port and never the ephemeral range, and record it in the registry below.

The registry — not cleverness in the number — is what actually prevents collisions. Check it before you assign; add your service when you do.

---

1. Why the default ports bite

The ports frameworks and tools reach for by default form a dense cluster that half the software world also uses:

3000 3001 4000 5000 5173 8000 8008 8080 8081 8443 9000 9090 …

On a dedicated single-service host these are fine. On our fleet they are not: hosts run gongfoo runners, nginx, sometimes more than one app, plus whatever a container or a dev shell brought up. Two things pick 8080/8081 and one fails to bind (EADDRINUSE) — or, worse, doesn't fail: it binds a different interface, the health probe hits the other service on that port, and you debug a green check that lies. Avoid the whole cluster.

2. The three ranges

Range	IANA class	Use for a listener?
0–1023	well-known / system	No. Requires privilege; reserved for standard services. TLS terminates at nginx (:443), so apps don't need these.
1024–49151	registered / user	Yes. This is where our services live.
49152–65535	dynamic / ephemeral	No. The kernel hands these out as source ports for outbound connections. A fixed listener here can collide with an ephemeral allocation and fail intermittently — the worst kind of bug.

So: registered range, and specifically a sparse part of it. The crowded cluster (§1) sits at the bottom of the registered range; climb out of it. A good default band is 20000–29999 — clear of the alt-HTTP mess below and the ephemeral range above, and sparsely used. 30000–39999 is equally fine (cortex already lives there).

3. Picking the number

1. Derive, don't guess. Human-chosen ports cluster (everyone likes round numbers and x080). Map the service name deterministically into the band instead:

   name=newsfeed
   python3 -c "import hashlib;print(20000 + int(hashlib.sha256('$name'.encode()).hexdigest(),16) % 10000)"
   # newsfeed -> 22672
   

   This is reproducible (anyone can re-derive it) and spreads services across the band.

2. Check the registry (§5). If the derived number is taken, bump by 1 until free, or pick a memorable nearby number — then it's a deliberate, recorded choice.

3. Record it in the registry with the same change that introduces the service.

4. A memorable hand-picked number in the band is equally valid (neuron = 13131, cortex = 31313). The rule is uncommon + registered + recorded, not hashed.

4. Consequences elsewhere

• firewalld (generic.md §9): ship the port in the app's named service XML. The registry and the XML must agree.
• SELinux (generic.md §10): a non-standard port the daemon binds must be labelled, or the bind is denied. semanage port -a -t http_port_t -p tcp <port> (guard with semanage port -l | grep so re-runs are no-ops). Do this in the host-prep step (infra-setup.sh), before the first service start.
• Binding scope: bind loopback (127.0.0.1) when nginx is on the same host, or the mesh-routable address when the proxy is on a different host (e.g. an API on one host fronted by the site's edge proxy on another). firewalld's named service bounds who may reach it; the registry bounds what else may bind it.
• Reverse proxy (reverse-proxies.md): the nginx upstream points at <host>:<port> — the same number as the registry and the service's bind config.

5. The registry

Canonical list of internal-service port assignments. Append here when you allocate a port; treat a duplicate as a bug. (Seeded from the services documented across this repo; extend as you encounter others — this table is authoritative going forward.)

Port	Service	Host(s)	Notes
5432	PostgreSQL	magrathea, frankie (standby)	standard well-known assignment; mTLS
13131	helexa neuron	each GPU host	OpenAI-compatible inference API
13132	helexa-bench read API	bob	benchmark telemetry
18443	gongfoo controller	golgafrinchans	agent-facing RPC (mTLS)
22672	newsfeed-api	slartibartfast	REST/JSON; fronted by oolon
28443	gongfoo agent	each runner host	controller-facing RPC (mTLS)
31313	helexa cortex API	hanzalova	unified OpenAI/Anthropic gateway
31314	helexa cortex metrics	hanzalova	Prometheus

443 (nginx edge, every proxy host) and the ephemeral range are intentionally omitted — they aren't allocations.

6. Checklist for a new listening service

1. Derive a candidate port in 20000–29999 from the service name (§3).
2. Check it's free in the registry (§5); bump if taken.
3. Record it in the registry in the same change.
4. Put the number in exactly these places, all agreeing: the service's bind config, its firewalld service XML (§9), its SELinux semanage port label (§10, in host prep), and any nginx upstream (reverse-proxies.md).