Ephemeral Publish and Claim Tokens

Use authenticated publish first

Agents should run agent-paste whoami --json before choosing --ephemeral. It exits 0 either way; check the JSON, not the exit code. If it reports you are signed in, publish normally without --ephemeral. If it reports "authenticated": false and the user can interact, run agent-paste login first. Use --ephemeral only when no login is available, or when the user explicitly asks for accountless publish.

Ephemeral is not the Free Plan. It is an unclaimed restricted tier: low write caps, 24 hour Auto Deletion, noindex, and script-disabled content serving while unclaimed. Use it for non-interactive text, markdown, images, and static HTML/CSS.

Flow

1. An agent runs agent-paste publish <path> --ephemeral.
2. If copied instructions include --claim-code <clm_...>, the agent preserves it on the publish command.
3. The CLI provisions an Ephemeral Workspace, then publishes through the normal Upload Session flow.
4. Human-readable output leads with unlisted_url, a working no-login Share Link. Relay this link for immediate viewing, not the private_url.
5. A signed-in human opens the claim_url to keep, unlock interactivity, and move the Artifact into their Personal Workspace. That browser session chooses the destination Workspace.

Ephemeral limits

Reads are not tied to the publisher allowance. They are gated only by the platform Artifact read rate limit. Unclaimed ephemeral content is also served with scripts disabled: text, markdown, images, and static HTML/CSS render, but JavaScript does not execute. After claim, newly minted viewer URLs can run interactive HTML inside the controlled Artifact Viewer. For interactive HTML, browser apps, or visualizations that need JavaScript, use authenticated publish instead.

Claim Token rules

• The token is returned once to the caller that provisioned the Ephemeral Workspace.
• The claim link carries the token in the URL hash, never the query string.
• The token is not embedded in Access Link Signed URLs.
• Expired, missing, or already redeemed tokens fail closed.

Claim Code rules

• A Claim Code has the public shape clm_... and is optional analytics attribution for copied prompts.
• It is not auth, ownership, billing, idempotency, a Claim Token, or a secret.
• When present on publish --ephemeral, the CLI sends it to the API and the API embeds it in the Claim Token for conversion attribution.
• It is never returned as claim_code, never added to unlisted_url or claim_url, and never placed in URL query strings.

After claim

Claiming reparents the Artifact into the signed-in member's Personal Workspace. There is no user-backed session before claim; after claim, pre-claim ephemeral credentials stop working. The Artifact moves to the Free Plan limits unless the destination Workspace is already Pro.