Relationships
#4837 The serve host passes an OAuth client from host.yaml to its children
Opened by zack · 11/17/2026· Shipped 11/17/2026
Issue 9 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4835 (swamp serve host).
Problem
In oauth mode a serve without an OAuth client registers one on its first start. That needs a collective key or a person. A workspace created through the API has neither, so it could not start unattended.
The host cannot read a client out of the root's datastore either: the host has no repo and no datastore.
Change
host.yaml can name one OAuth client and its secret file. The host passes them to each child with the flags serve already has, --oauth-client-id and --oauth-client-secret-file.
- The host checks at startup that the secret file exists and is readable, and refuses to start when it is not.
- The host passes the path of the secret file, not its contents. The secret never appears in a child's arguments, in the host's log or in its json output.
- A host with no client in
host.yamlpasses neither flag, and each child behaves as a serve does today. - A child in
tokenornonemode is unaffected.
Done when
- A workspace in
oauthmode starts with no stored client and no collective key, using the client fromhost.yaml. - The root and every workspace are given the same client.
- A missing or unreadable secret file is refused at startup, naming the path.
- Tests cover the child arguments with and without a client in
host.yaml.
Known limit
Workspace processes run as one OS user, so code in any workspace can read the secret file. The design lists this under Limits: it separates failures, not hostile code.
Open question
Whether swamp-club accepts one OAuth client used from many workspace addresses. The design lists this under Open questions. If the answer is no, this issue changes shape, so it is worth settling before the work starts.
Shipped
Click a lifecycle step above to view its details.
zack commented 11/17/2026, 8:58:42 PM
Open question settled: one OAuth client from many workspaces is fine
Checked against swamp-club main. Nothing there ties a client to one serve or one address, so this issue keeps its shape.
- Instance rows are per process.
serve_instancesrows are keyed on client id plus instance id (mongo-serve-instance-repository.ts), on purpose so sibling processes on one client don't replace each other. Heartbeats name their instance id, so each one updates only its own row. - Registration is optional. A serve registers and heartbeats only when it holds a collective key (
src/cli/commands/serve.ts). A workspace started only with the host.yaml client never registers. - No address reaches swamp-club. The device flow sends client id, secret and device code. Registration carries no address, and the only redirect URI is
http://localhost. The device client validator checks only that the client exists and is not disabled (lib/auth.ts).
Effects to know about, none blocking:
- With a collective key, each workspace is its own row under the same client name and the same hostname. Serve sends no tags, so the rows are indistinguishable apart from the instance id. Tagging each registration with its workspace address would fix that later; whether a host shows as one serve is a display choice.
- The device approval page shows the client's name, the same for every workspace.
- Disabling the client in swamp-club stops new sign-ins on every workspace at once, in line with the Known limit.
The design doc's Open questions entry will be updated in the PR for this issue.
Sign in to post a ripple.