Relationships
#4917 Docs: the serve workspaces design keeps one list of workspaces, the registry, and a host needs no host folder
Opened by zack · 11/19/2026· Shipped 11/19/2026
First of six steps that merge a serve host's workspaces into the workspace registry and make the host folder optional. swamp-club#4865 lists the whole sequence. One PR, docs only.
Problem
design/surfaces/serve-workspaces.md describes two lists of workspaces: the folders in a host folder's workspaces/, and the workspace registry (<config dir>/workspaces.json). Its Registered workspaces section bridges the two with four name and folder rules. The plan is now one list, the registry, and a host that needs no host folder.
The doc's status header is also out of date. It says lifecycle and sign-in are not built. Items 8 to 15 of its execution plan have landed.
Change
Rewrite the design so the code issues have a section to point at. Each code PR still records the decisions it makes.
- Status header. Say what is built today: addresses with a path, the host, lifecycle, sign-in and default off. Registered workspaces and the dashboard are not.
- One list. The registry is the list of workspaces on a machine. A host serves entries from it. A workspace made by
workspace.createis a registry entry like any other. - Listed is not started. Every registered workspace is listed on the host and has a status file. A serve starts only when its wanted file says
active. This is already the rule; say it once, for every workspace. - Whose a workspace is. A workspace a request created is the host's: grants on
workspace:<pattern>reach it andworkspace.deleteremoves its folder. Any other registered workspace is the operator's own: delete refuses it and only the root's admins may suspend or resume it. Say how the host tells them apart in each layout. - The host folder is optional. With
--host-dir, or ahost.yamlin the current folder, the host runs as it does today. With neither, it reads<config dir>/host.yamland keeps its wanted and status files in<data dir>/host/. - Compatibility. Add a section that states what stays true for a host folder that exists today:
- the same command, the same
host.yamland the same addresses; - every workspace that ran before an upgrade runs after it, with no step by the operator;
- repos, wanted files and status files stay where they are, and nothing is moved;
- new workspaces on a host with a host folder are still created in its
workspaces/; - the registry file gains no field and no schema version, so an older swamp reads and rewrites it without loss;
- an older
swamp serve workspaceclient works against a newer root, and a newer client against an older root.
- the same command, the same
- Execution plan. Replace item 19 with five items, one per code issue, in order: a host registers the workspaces it runs; the host takes its workspaces from the registry; a workspace registered anywhere is listed and served in place (swamp-club#4865); a host with no host folder; a host with no host folder creates workspaces.
- Limits. Add: two hosts run by one user share one registry, so each lists every entry and names must be unique across both; run a second host under its own
SWAMP_HOME. Add: a host depends on a registry it can read. design/surfaces/workspace.md. Say that a serve host writes the registry too, and that hosted workspaces appear inswamp workspace listand on theswamp startpage.
Done when
- The Registered workspaces section no longer describes a second list, and its four rules are replaced by the ones swamp-club#4865 keeps.
- The execution plan's items match the five code issues, and each names its issue.
- The status header matches what is on
main. last-verifiedis updated on both docs.
Out of scope
- Any code.
design/surfaces/hub.md, which is not onmain.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.