`f domains`

Manage shared local *.localhost routing with a single proxy on port 80.

Why

Without this, each repo can start its own proxy and race for port 80. f domains centralizes ownership with one engine at a time.

State lives in:

~/.config/flow/local-domains/routes.json
runtime artifacts under ~/.config/flow/local-domains/

Engines

docker (default): shared nginx container (flow-local-domains-proxy)
native (experimental): local C++ daemon (domainsd-cpp)

Select engine per command:

bash

f domains --engine docker up
f domains --engine native up

Or via env:

bash

export FLOW_DOMAINS_ENGINE=native

Commands

bash

f domains list
f domains add linsa.localhost 127.0.0.1:3481
f domains rm linsa.localhost
f domains up
f domains down
f domains doctor
f domains --engine native up
f domains --engine native down
f domains --engine native doctor

Behavior

f domains up
- starts shared proxy on :80
- fails fast if another process/container owns port 80
f domains add
- validates host ends with .localhost
- validates target format host:port
- refuses overwrite unless --replace
- reloads proxy if already running
f domains doctor
- shows route count
- shows current owner of port 80
- highlights conflict ownership

Native notes (experimental)

Requires clang++ to build tools/domainsd-cpp/domainsd.cpp.
Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.
Native daemon has built-in overload shedding (503) and upstream timeout protection (504 on connect timeout).
HTTP/2/TLS are not implemented yet.
See docs/local-domains-domainsd-cpp-spec.md.
myflow-specific setup: docs/myflow-localhost-runbook.md.
Lifecycle integration: configure [lifecycle.domains] and use f up / f down.

macOS no-docker bind to :80

If native startup fails with Permission denied on 127.0.0.1:80, install launchd socket mode once:

bash

cd ~/code/flow
sudo ./tools/domainsd-cpp/install-macos-launchd.sh

Then run:

bash

f domains --engine native up

This keeps routing fully native and avoids Docker overhead while still using port 80.

Native tuning envs

You can tune the native daemon at startup via environment variables:

bash

FLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128
FLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000
FLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000
FLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000
FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8
FLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256
FLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000
FLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000

Recommended Repo Pattern

Instead of per-repo docker proxy tasks:

toml

[[tasks]]
name = "domains-up"
command = "f domains add myapp.localhost 127.0.0.1:3000 && f domains up"

This keeps one proxy process for all repos and avoids accidental domain hijacking.