Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

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 workspace

The 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 optional root: 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 passes parseWorkspaceName is 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, --address with the child's public address, --trusted-hosts with the host's public name, --trust-proxy and --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 mode none relies 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 mode none.
  • 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 the swamp serve workspace commands. Issues 10 to 12.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 2 MORETRIAGE+ 6 MOREREVIEW+ 14 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/17/2026, 8:25:59 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/17/2026, 3:17:48 PM

Sign in to post a ripple.