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

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; --json emits it as an event of its own before listening.
  • swamp serve host --help says 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 (locateHostYaml and its error)
  • src/serve/host/host_config.ts (the defaults)
  • src/cli/commands/serve_host.ts, src/presentation/renderers/serve_host.ts
  • design/surfaces/serve-workspaces.md (The host, the host.yaml table)
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 4 MOREREVIEW+ 6 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/20/2026, 10:18:49 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/20/2026, 9:40:25 PM

Sign in to post a ripple.