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

Relationships

#4848 Workspace services: create, list, get, suspend, resume and delete a hosted workspace

Opened by zack · 11/17/2026· Shipped 11/18/2026

Issue 10 of the execution plan in design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4836 (wanted and status files), merged.

Problem

The host reads a wanted file for each workspace and acts on it, but nothing writes one for a request, and nothing creates a workspace. An operator makes each workspace by hand and suspends it by editing a file.

Change

Add the workspace application services in src/libswamp/hosted_workspace/. They work on a host's workspaces/ folder through the HostedWorkspace aggregate and its repository, which already exist. They are exported from mod.ts.

  • Create. Refuses a name that parseWorkspaceName refuses, and a name already taken by a folder, a wanted file or a status file. Sets the repo up in a folder under a hidden temporary name, then renames it into place, so the host never starts half a workspace. Writes the workspace's serve.yaml: the root's auth mode, OAuth provider and admission lists, and the caller as its first admin. Records the creator and the time in the wanted file. A create that fails removes what it made and leaves no entry under the name.
  • Create never starts a serve. The design's default-off rule: the host starts a serve only when a wanted file says active. Create writes the wanted file as suspended before the rename, so the new workspace is listed and has no serve until a resume. The host already leaves a wanted file alone while its folder does not exist.
  • The provisioner. Setting up a repo runs as a child process in the new folder. The calling process never loads another workspace's extensions.
  • List. Names, addresses and states.
  • Get. One workspace: state, restarts and the host's reason when it is not ready.
  • Suspend and resume. Each writes the wanted file with a new changedAt. Resume is the only thing that starts a workspace's serve. A changed active record is also what takes a workspace out of failed.
  • Delete. Writes deleted. The host stops the serve and removes the folder and both files.

A decision this issue makes

In oauth mode a new workspace's first start looks up each admin name. Without a collective key in the host's environment that lookup is a device grant, so a person has to complete it. Create has to avoid that for the creator. The design names two ways and leaves the choice to this issue:

  • create seeds the workspace's oauth-resolved-admins from names the root already resolved, or
  • serve gains an admin entry form that is already resolved.

The PR states which it chose and why, and updates the design doc.

Done when

  • An integration test runs each service on a temp folder with the real file store.
  • A scan of the folder taken at any point during a create never lists the new workspace until it is whole.
  • A created workspace has its wanted file, saying suspended, before its folder appears, and the host's reconciler never starts it. A resume then starts it.
  • A failed set-up leaves no folder and no wanted file under the name.
  • Create refuses a taken name, whether a folder, a wanted file or a status file holds it.
  • The services are exported from mod.ts and the libswamp fitness rules pass.
  • Test fixtures that initialise a repo pass tools: [].

Out of scope

  • workspace.* requests on the root. The next issue in the plan.
  • The swamp serve workspace commands.
  • The workspace kind in grants. The services take a caller and do no authorization of their own.
  • Workspaces from the workspace registry. Item 19 in the plan.
  • The host's own default for a folder with no wanted file. Item 20 in the plan.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 21 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/18/2026, 3:17:53 PM

Click a lifecycle step above to view its details.

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

Sign in to post a ripple.