Why
Companion issue to relaycast-cloud#61 (https://github.com/AgentWorkforce/relaycast-cloud/issues/61) — read that first for full context. Short version: the Cloud dashboard's copy-pasteable attach command (agent-relay node agent attach <agent> --node <node> --mode drive) doesn't work on a machine without a matching local workspace-key.json — blocking Khaliq's cofounder Will from using it. PR #1502 added --workspace-key as a raw-key flag, but embedding the actual long-lived rk_live_... key in a copy-pasteable UI string was rejected as a real credential-exposure risk.
The design, agreed with Khaliq directly (2026-08-14)
A single pasted command still works in one step, but instead of a raw key it carries a short-lived, scoped join-ticket. This CLI redeems the ticket against relaycast-cloud#61's new endpoint to silently bootstrap a real local credential, then proceeds with the existing --node attach flow unchanged.
Scope for this issue (relay CLI side only)
- New flag on
node agent attach, e.g. --join-ticket (name it what reads best given the actual redemption endpoint's shape once relaycast-cloud#61 defines it — coordinate on the exact wire contract, don't invent your own).
- When present: call the redemption endpoint, get back a real local-persistable credential, write it to the standard local credential location (same place --workspace-key / the existing resolution ladder in resolveWorkspaceSelection already checks), then proceed with the normal attach flow.
- Do NOT persist or log the raw ticket itself after redemption — it should behave like a one-time-use bootstrap, not a reusable secret.
- Add tests: successful redemption + attach, expired/invalid ticket (clear error, not the generic 'no workspace key found' message), and that the redeemed credential is what --node attach actually uses afterward (not silently ignored, falling through to the existing ladder).
Explicitly NOT in scope here
The relaycast-cloud ticket-minting/redemption endpoint itself — that's relaycast-cloud#61, filed alongside this one. Do not implement server-side changes here.
Sequencing
Do NOT merge this before relaycast-cloud#61's endpoint is live in production — this CLI flag is nonfunctional without it (same order cloud#2995 had to land before relay#1484's CLI rollout was useful, tonight's precedent). Note this explicitly in your PR description.
Why
Companion issue to relaycast-cloud#61 (https://github.com/AgentWorkforce/relaycast-cloud/issues/61) — read that first for full context. Short version: the Cloud dashboard's copy-pasteable attach command (
agent-relay node agent attach <agent> --node <node> --mode drive) doesn't work on a machine without a matching local workspace-key.json — blocking Khaliq's cofounder Will from using it. PR #1502 added --workspace-key as a raw-key flag, but embedding the actual long-lived rk_live_... key in a copy-pasteable UI string was rejected as a real credential-exposure risk.The design, agreed with Khaliq directly (2026-08-14)
A single pasted command still works in one step, but instead of a raw key it carries a short-lived, scoped join-ticket. This CLI redeems the ticket against relaycast-cloud#61's new endpoint to silently bootstrap a real local credential, then proceeds with the existing --node attach flow unchanged.
Scope for this issue (relay CLI side only)
node agent attach, e.g. --join-ticket (name it what reads best given the actual redemption endpoint's shape once relaycast-cloud#61 defines it — coordinate on the exact wire contract, don't invent your own).Explicitly NOT in scope here
The relaycast-cloud ticket-minting/redemption endpoint itself — that's relaycast-cloud#61, filed alongside this one. Do not implement server-side changes here.
Sequencing
Do NOT merge this before relaycast-cloud#61's endpoint is live in production — this CLI flag is nonfunctional without it (same order cloud#2995 had to land before relay#1484's CLI rollout was useful, tonight's precedent). Note this explicitly in your PR description.