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

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.yaml passes neither flag, and each child behaves as a serve does today.
  • A child in token or none mode is unaffected.

Done when

  • A workspace in oauth mode starts with no stored client and no collective key, using the client from host.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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 10 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/17/2026, 10:50:35 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/17/2026, 8:28:06 PM
Editable. Press Enter to edit.

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_instances rows 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:

  1. 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.
  2. The device approval page shows the client's name, the same for every workspace.
  3. 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.