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-dirgiven: that folder, as today.- No flag and a
host.yamlin 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.yamlit 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.yamlhas 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 withswamp workspace importorswamp workspace create, and a root admin resumes it. workspace.createis refused, with a message that says this host has no folder to create workspaces in. swamp-club#4921 lifts that.list,get,suspendandresumework.
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 holdshost.yaml, reads the same file, keeps its files in the same places and creates workspaces in the sameworkspaces/. Nothing is moved or rewritten. - The only change such a host sees is the lock.
- A machine that has both a
host.yamlin 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-dirand nohost.yamlin 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-dirand 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.yamlanywhere, the error names every place the host looked. swamp serve workspace createagainst a host with no host folder is refused with a message that says why.swamp serve host --helpdescribes both layouts.- The tests supply the config and data dirs with
withMockedEnvand spawn no processes.
Where to look
src/cli/commands/serve_host.ts(readHostYaml, the--host-dirdefault) andsrc/serve/host/host_config.ts(hostDir,workspacesDir, the path checks).src/serve/host/serve_host.tsandsrc/serve/host/serve_process.tsfor what the root is given.src/serve/host_root_workspaces.tsandsrc/libswamp/hosted_workspace/deps.tsfor the root's side.src/infrastructure/persistence/paths.tsfor the config and data dirs.src/infrastructure/persistence/sqlite_read_model.tsfor an existingtryLock.
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.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.