# Ephemeral Publish and Claim Tokens

Restricted accountless publish for when no login is available.

Human page: /docs/ephemeral
Markdown page: /docs/ephemeral.md

## 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

| Limit | Value |
| --- | --- |
| Daily new Artifacts | 20 |
| Auto Deletion | 24 hours |
| Indexing | `noindex` |
| Scripts | Present but inert while unclaimed; after claim, interactivity runs through the Artifact Viewer |

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.