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

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 create creates 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 in HostConfig.parse apply 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 as swamp serve with no flags does (src/serve/serve_config.ts), from its own serve.yaml only, since the host withholds the serve settings in its environment from every child. Today that is auth mode none, 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's serve.yaml, as for any workspace.
  • The host's existing refusals apply. A child in auth mode none is 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's serve.yaml (naming its path) or to set root: to a repo of the operator's own.
  • An explicit root: wins. Naming a root in host.yaml means 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 --json events 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, the host.yaml table and The root workspace in design/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 by workspace.list like 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 none on 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.ts
  • src/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.ts
  • design/surfaces/serve-workspaces.md
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/21/2026, 1:27:42 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/21/2026, 12:04:20 AM

Sign in to post a ripple.