Relationships
#4971 The first swamp serve host run creates host.yaml in the config dir with reasonable defaults instead of exiting
Opened by zack · 11/20/2026· Shipped 11/20/2026
Problem
swamp serve host with no host.yaml exits with an error telling the operator to write one. Every key but address already has a default (src/serve/host/host_config.ts), and on loopback the address is the listener's own, so a first run that only wants to try the host still has to write a file whose contents the host could have chosen.
Change
When swamp serve host finds no host.yaml, it writes <config dir>/host.yaml with reasonable defaults, logs the path it wrote, and starts from it.
listen.host: 127.0.0.1,listen.port: 8080,address: http://127.0.0.1:8080. On loopback with no proxy this address is right by construction, and off loopback needs TLS files the host cannot guess, so the default never listens off loopback.- The keys left unset (
root,listen.cert-file/key-file,trust-proxy,oauth-client) appear as comments that say what each does, so the file is also its own reference. - The file is created exclusively and never overwritten: an existing
host.yaml, even an invalid one, is read as now and reported if it fails to parse. Two hosts starting at once must not both write it. - Log mode prints a line naming the file it created;
--jsonemits it as an event of its own beforelistening. swamp serve host --helpsays the first run creates the file.
Open question
A host with no root cannot take workspace.* requests or issue sign-in codes, so swamp serve workspace create|list|resume|rm have nothing to talk to and a workspace is started by editing its wanted file. Should the first run also make a root repo (outside <data dir>/host/, which may hold no repo) and name it in root:? If so, the issue must decide what its serve.yaml holds: auth mode none works on loopback but is deprecated, while oauth needs admins and a device grant on first start. Without a root, the log line should say what a root is for and how to add one.
Depends on
Simpler after the host folder layout is removed (swamp-club#4970), since there is then one place host.yaml lives. Without that, the default goes in the config dir, the no-host-folder layout, and a host folder is never created implicitly.
Where to look
src/serve/host/host_layout.ts(locateHostYamland its error)src/serve/host/host_config.ts(the defaults)src/cli/commands/serve_host.ts,src/presentation/renderers/serve_host.tsdesign/surfaces/serve-workspaces.md(The host, thehost.yamltable)
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.