Relationships
#4835 swamp serve host: one listener that runs a serve per workspace folder
Opened by zack · 11/17/2026· Shipped 11/17/2026
Issue 7 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4805 (the supervisor) and swamp-club#4804 (the router), both merged.
Problem
The supervisor and the router exist in src/serve/host/, but nothing runs them. There is no command an operator can start, no host folder and no listener.
Change
Add the command swamp serve host. It runs in a host folder:
<host folder>/
host.yaml the listener, the public address, the root
workspaces/<name>/ one repo per hosted workspaceThe host has no repo, no extensions and no datastore, and it authenticates no one.
host.yaml. It names the listener and its TLS certificate, the host's public address, the optionalroot:repo and whether the host is itself behind a proxy. A bad file is refused at startup with the field that is wrong.- The folder is the list. Every repo folder in
workspaces/whose name passesparseWorkspaceNameis a workspace. The host scans the folder at startup and watches it, so a folder an operator adds or removes while the host runs is picked up. - Children. The host gives the supervisor one child per workspace and one for the root, each with the child flags:
--host 127.0.0.1,--port 0,--addresswith the child's public address,--trusted-hostswith the host's public name,--trust-proxyand--exit-on-stdin-close. A workspace's address is<host address>/w/<name>. The root keeps the host's address. - Routing. The router's directory is answered from the supervisor's statuses. A host with no
root:answers 404 outside/w/. - Listener. TLS, with the certificate from
host.yaml. - Auth mode
none. A serve in auth modenonerelies on its loopback bind to stay private, and behind the router that bind no longer hides it. A host whose listener is off loopback refuses to start or route to a child in auth modenone. - Shutdown. SIGTERM and SIGINT stop the children through their drain paths first, then close the listener.
- Output. Log and json modes. The json listening line names the host's address and port, as serve's does.
The command loads lazily, like every other command.
The fitness rule for src/serve/host/ lands here: an integration/*_rules_test.ts that keeps the folder from importing the model, vault and datastore registries.
Done when
- An integration test runs a host in-process with a fake process port and port-0 serve stand-ins. A root and two workspaces made by hand answer at their own addresses.
- The same test covers a workspace folder added while the host runs, one removed while it runs, a host with no root, and a shutdown that stops every child.
- A host with an off-loopback listener refuses a child in auth mode
none. - The fitness rule passes, and fails when a registry import is added.
- A journey that spawns the binary belongs in
swamp-uat.
What this gives us
After this issue an operator who sets each workspace up by hand has a multi-workspace host.
Out of scope
- Suspend, resume and delete. Wanted and status files are issue 8 in the plan.
- The OAuth client in
host.yaml. Issue 9 in the plan. workspace.*requests and theswamp serve workspacecommands. Issues 10 to 12.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.