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

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.create is 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 and workspace.delete removes 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 a host.yaml in the current folder, the host runs as it does today. With neither, it reads <config dir>/host.yaml and 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.yaml and 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 workspace client works against a newer root, and a newer client against an older root.
  • 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 in swamp workspace list and on the swamp start page.

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-verified is updated on both docs.

Out of scope

  • Any code.
  • design/surfaces/hub.md, which is not on main.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 6 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/19/2026, 9:32:33 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/19/2026, 9:08:55 PM

Sign in to post a ripple.