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

Relationships

#4920 swamp serve host runs without a host folder: host.yaml in the config dir and its state in the data dir

Opened by zack · 11/19/2026· Shipped 11/20/2026

Fifth 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. Depends on swamp-club#4865 (the registry is the host's list).

Problem

swamp serve host needs a host folder: a folder that holds host.yaml and workspaces/. Once the registry is the host's list (swamp-club#4865), the folder holds no fact about which workspaces exist. It is only where the host keeps its config and its wanted and status files. Swamp already has a config dir and a data dir for that.

The folder is also not a boundary. The host pins every child's SWAMP_HOME and SWAMP_CONFIG_DIR to its own, so every workspace already shares the host user's dirs.

Change

A host runs with no host folder. A host that has one runs exactly as it does today.

Which layout

  • --host-dir given: that folder, as today.
  • No flag and a host.yaml in the current folder: the current folder, as today.
  • Otherwise: <config dir>/host.yaml, with the host's state in <data dir>/host/.
  • The host logs which host.yaml it read. With none in any of these places, the error names all of them.

With no host folder

  • <data dir>/host/ holds the wanted files, the status files, the per-name locks and nothing else. It holds no repo, and the host registers nothing from it.
  • Relative paths in host.yaml (listen.cert-file, listen.key-file, root, oauth-client.secret-file) are relative to the config dir.
  • host.yaml has the same keys. It still refuses unknown ones.
  • The root is given the state folder where it is given workspaces/ today.
  • Every workspace is one of the operator's own, since the host has no workspaces/ (swamp-club#4865, Whose a workspace is). An operator adds one with swamp workspace import or swamp workspace create, and a root admin resumes it.
  • workspace.create is refused, with a message that says this host has no folder to create workspaces in. swamp-club#4921 lifts that. list, get, suspend and resume work.

One host per state folder

  • The host takes an exclusive lock on a file in its state folder and holds it while it runs. The kernel releases it when the process dies, so there is no stale lock to judge.
  • A second host on the same state folder exits with a message that names the folder. The first is not disturbed.
  • This applies to a host folder too. Two hosts on one host folder were never valid, and nothing stopped them.

Compatibility

  • A host started with --host-dir, or in a folder that holds host.yaml, reads the same file, keeps its files in the same places and creates workspaces in the same workspaces/. Nothing is moved or rewritten.
  • The only change such a host sees is the lock.
  • A machine that has both a host.yaml in the current folder and one in the config dir uses the current folder's, as it does today.

Decisions this issue makes

  • The OAuth client's secret file. Today it may not be inside workspaces/ or the root. With no host folder, the repos the host runs are wherever the registry says. The expected answer: the host refuses to start a workspace whose folder holds the secret file, and says so in its status.
  • The refusal's code for create on a host with no host folder, and its place in the client's list of codes whose message the root wrote. An older client must still show the root's message.
  • How the root learns that the host has no workspaces/. The flags between the host and its root are hidden and both sides are one binary, so they can change freely.

Done when

  • With no --host-dir and no host.yaml in the current folder, the host reads <config dir>/host.yaml, writes its status files under <data dir>/host/, and serves its root and each registered workspace that is resumed.
  • A host folder that exists today runs unchanged with --host-dir and from inside the folder. No file in it is moved or rewritten.
  • A second host on the same state folder refuses to start, in both layouts. A host killed outright leaves nothing that blocks the next start.
  • With no host.yaml anywhere, the error names every place the host looked.
  • swamp serve workspace create against a host with no host folder is refused with a message that says why.
  • swamp serve host --help describes both layouts.
  • The tests supply the config and data dirs with withMockedEnv and spawn no processes.

Where to look

  • src/cli/commands/serve_host.ts (readHostYaml, the --host-dir default) and src/serve/host/host_config.ts (hostDir, workspacesDir, the path checks).
  • src/serve/host/serve_host.ts and src/serve/host/serve_process.ts for what the root is given.
  • src/serve/host_root_workspaces.ts and src/libswamp/hosted_workspace/deps.ts for the root's side.
  • src/infrastructure/persistence/paths.ts for the config and data dirs.
  • src/infrastructure/persistence/sqlite_read_model.ts for an existing tryLock.

Out of scope

  • Moving an existing host folder's files into the config and data dirs. An operator can do it by hand; the design doc says how. A command for it can follow.
  • Naming the root by its registry name in host.yaml.
  • Creating a workspace on a host with no host folder. That is swamp-club#4921.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 7 MOREFINDINGS+ 14 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/20/2026, 7:57:42 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/20/2026, 6:39:58 PM

Sign in to post a ripple.