Relationships
#4975 A serve host with no root in host.yaml makes its root an ordinary workspace, registered like any other, with serve's default auth
Opened by zack · 11/20/2026· Shipped 11/21/2026
Problem
A serve host with no root: in host.yaml has no root workspace, so nothing takes the workspace.* requests or issues sign-in codes. swamp serve workspace create|list|resume|rm have nothing to talk to, and a workspace is started or stopped only by editing its wanted file in the host's state folder. Since swamp-club#4971 the first host run writes a default host.yaml, but it names no root, so a fresh host is never fully usable until the operator makes a repo and wires it in by hand.
The root cannot be folded into the host process: the host runs no repo code, opens no datastore and authenticates no one (design/surfaces/serve-workspaces.md, The idea and Why this shape; integration/serve_host_isolation_rules_test.ts). Tokens, grants, audit and sign-in live in a serve's own datastore, so the root stays a child serve. It needs nothing special beyond that: it can be an ordinary workspace.
Change
When host.yaml sets no root, the host's root is an ordinary workspace: created like any other, registered in the workspace registry, and started as the root.
- Just another workspace. The root workspace is created where
swamp workspace createcreates one, in the workspace location (workspaces.dir, or<data dir>/workspaces), through the same create path (src/libswamp/hosted_workspace/create.ts): a repo set up as create sets one up, and an entry in<config dir>/workspaces.json, under the registry's create lock so two hosts starting at once make it once. It is not a special folder: never inside the host's state folder<data dir>/host/, and never in the cache dir. The existing root containment checks inHostConfig.parseapply unchanged. - Found again by its registry entry. On later starts the host finds the root workspace through the registry and uses it as it is; it is never re-created or re-initialised. If the entry exists but its folder is gone, the host reports it rather than silently making a new root.
- Auth follows plain
swamp serve's defaults. The host writes no auth settings into the root workspace's.swamp/serve.yaml. The root resolves its auth mode, admins and admission lists exactly asswamp servewith no flags does (src/serve/serve_config.ts), from its ownserve.yamlonly, since the host withholds the serve settings in its environment from every child. Today that is auth modenone, with serve's deprecation warning; when serve's default changes, the root follows with no change here. The operator changes the root's auth by editing that workspace'sserve.yaml, as for any workspace. - The host's existing refusals apply. A child in auth mode
noneis refused off loopback or behind a proxy (HostConfig.noAuthRefusal). The root workspace is no exception: on such a host it is refused, and the message says to set an auth mode in the root workspace'sserve.yaml(naming its path) or to setroot:to a repo of the operator's own. - An explicit
root:wins. Naming a root inhost.yamlmeans no root workspace is created or started for it; one made earlier stays an ordinary registered workspace and is never deleted. - Reporting: the host logs the root workspace's name and folder when it creates it and when it starts it, and the
--jsonevents say which workspace is the root. The first-run created line from swamp-club#4971 names the root workspace instead of telling the operator to add one. - Docs:
swamp serve host --help, thehost.yamltable and The root workspace indesign/surfaces/serve-workspaces.md.
Open questions
- The root workspace's name, and how the host recognises it on later starts: a fixed reserved name, or a mark on its registry entry.
- Whether it is also served at
<address>/w/<name>and shown byworkspace.listlike any other workspace, or only at the address itself. Being an ordinary workspace argues for listing it, but suspend and delete on it must not let a caller remove the root through itself. - With auth mode
noneon loopback, anyone on the machine can create and delete workspaces through the root. Following serve's default means accepting that until serve's default changes; the created log line should say so.
Depends on
swamp-club#4970 (remove the host folder layout), so there is one layout and one workspace location. Builds on swamp-club#4971.
Where to look
src/serve/host/host_config.ts(root, containment checks,noAuthRefusal)src/libswamp/hosted_workspace/create.ts,src/serve/host/workspace_registration.ts(hostConfiguredParent,hostWorkspaceStore),src/libswamp/workspace/hosted_roster.tssrc/serve/host/serve_host.ts,src/serve/host/child_env.ts(starting the root, withheld serve settings)src/serve/serve_config.ts(how serve resolves its auth mode)src/cli/commands/serve_host.ts,src/presentation/renderers/serve_host.tsdesign/surfaces/serve-workspaces.md
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.