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

Relationships

#4877 The CLI signs in to a hosted workspace through the root, after one login to the host

Opened by zack · 11/18/2026· Shipped 11/19/2026

Issue 15 of the execution plan in design/surfaces/serve-workspaces.md. One PR. Depends on swamp-club#4876 (the sign-in exchange on serve).

Problem

The sign-in exchange lets a root token become a workspace token, but nothing in the CLI uses it. A person still runs swamp auth server-login once for every workspace address, or the command they ran fails as not signed in.

Change

The CLI signs in to a workspace through the root by itself. The design section is Sign-in.

  • When. The CLI is given a server address <address>/w/<name>, it has no stored token for that address, it holds one for <address>, and the workspace's /auth/info offers the exchange.
  • What it does. It asks the root at <address> for a sign-in code for <name>, gives the code to the workspace, and stores the token it gets back under the workspace's address in servers.json. Then it runs the command.
  • Where. In the one place a command resolves a server token, so every command that talks to a serve gets it: the WebSocket and /api/v1/request calls, workflow cancel, and a team-mode checkout's datastore client. The PR lists any caller that resolves a token another way.
  • The host's address comes from the address the user gave. It is that address with the trailing /w/<name> removed, so a host behind a path keeps its path. It is never taken from what the workspace answers. The root token is sent only there.
  • No prompt and no extra output. The exchange needs no person, and it adds nothing to stdout in log or json mode.
  • An expired workspace token. When the workspace refuses a stored token as expired or unknown, the CLI exchanges once more and tries again. It does not loop.
  • swamp auth server-login to a workspace's address still works, and a token stored that way is used as it is.

When it cannot

  • No token for <address>: the existing not-signed-in error, which now names swamp auth server-login <address> as the one sign-in that covers the host's workspaces.
  • The workspace offers no exchange: the existing error, unchanged.
  • The root refuses the code, or the workspace's admission lists refuse the principal: the error says which, and that signing in to the host again will not help the second.

Decisions this issue makes

The PR states what it chose and updates the design doc.

  • Signing out of the host. Whether swamp auth signing out of <address> also forgets the workspace tokens that came from it. They expire with the root token either way.
  • Two commands at once. Two CLI processes that both find no workspace token may both exchange. The expected answer is that both succeed and the later write to servers.json wins, with no lock beyond the one the file already has.

Done when

  • --server <host address>/w/<name> works after one swamp auth server-login to the host, with no token stored for the workspace beforehand.
  • servers.json then holds the workspace's token under the workspace's address, and the next command makes no exchange.
  • The root token is never sent to the workspace. A test asserts on every request the workspace received.
  • A host address with a path, such as one behind a reverse proxy, resolves to the right root.
  • A workspace that offers no exchange, and a CLI with no host token, each give the existing error.
  • An expired workspace token is replaced by one exchange and the command succeeds. A second refusal fails the command.
  • A team-mode checkout whose serve address is a workspace's address signs in the same way.
  • Tests run in-process against port-0 servers, with the config folder supplied by withMockedEnv.

Out of scope

  • The exchange itself. swamp-club#4876.
  • The dashboard signing in under a workspace segment. Item 17.
  • Workers. A worker connects with its own token at the workspace's address.
  • Listing a host's workspaces from the CLI. swamp-club#4850.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 11 MOREREVIEW+ 42 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/19/2026, 7:58:42 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/18/2026, 9:32:06 PM

Sign in to post a ripple.