# agent-paste full docs



This is the complete machine-readable public docs corpus for agent-paste.

Human docs start at /docs. Per-page Markdown twins live under /docs/{slug}.md.



# agent-paste docs

Official public usage docs for humans and agents.

- Human docs: /docs
- Markdown index: /docs.md
- Full corpus: /llms-full.txt
- Agent guide: /agents.md
- LLM summary: /llms.txt

## Pages

- [Getting Started](/docs/getting-started.md) - Install the CLI, check auth, publish, and hand off your first Artifact.
- [CLI Reference](/docs/cli.md) - The CLI is the primary publish surface for humans, agents, and CI.
- [Artifact Model](/docs/artifact-model.md) - Artifacts, Revisions, Access Links, and Agent View are the core handoff objects.
- [Sharing and Access Links](/docs/sharing.md) - Share human-readable viewers and machine-readable manifests without exposing credentials.
- [Ephemeral Publish and Claim Tokens](/docs/ephemeral.md) - Restricted accountless publish for when no login is available.
- [Dashboard](/docs/dashboard.md) - The dashboard is the human control plane for Workspaces, Artifacts, links, billing, and settings.
- [MCP Server](/docs/mcp.md) - Hosted agents without CLI access can publish, inspect, revise, and share text Artifacts over OAuth-only MCP.
- [Limits and Retention](/docs/limits.md) - Billing-enabled limits keep handoffs useful without turning the service into permanent storage.
- [Safety and Content Isolation](/docs/safety.md) - agent-paste treats uploaded work as untrusted content and isolates serving from control-plane auth.



# Getting Started

Install the CLI, check auth, publish, and hand off your first Artifact.

Human page: /docs/getting-started
Markdown page: /docs/getting-started.md

## Install

Use `npx @zaks-io/agent-paste ...` for one-shot Node.js 24 runs. After the standalone installer, use the installed `agent-paste ...` command; both run the same CLI.

```sh
npx @zaks-io/agent-paste publish ./report
curl -fsSL https://agent-paste.sh/install.sh | sh
```

```powershell
irm https://agent-paste.sh/install.ps1 | iex
```

The installers verify release checksums before placing `agent-paste` on your PATH. The macOS binary is codesigned and notarized.

## Authenticate

For interactive use, run `agent-paste login`. It opens a browser OAuth flow and stores a scoped local credential in your OS keyring when available.

```sh
agent-paste login
agent-paste whoami
```

Agents should run `agent-paste whoami --json` before falling back to accountless publish. It exits `0` whether or not you are signed in, so check the JSON rather than the exit code: a signed-in response means use normal authenticated publish, not `--ephemeral`; `"authenticated": false` means no usable credential.

## Publish

```sh
agent-paste publish ./report
agent-paste publish ./report --artifact-id art_01H...
```

A publish walks a file or folder, creates an Upload Session, uploads bytes to signed upload-worker URLs, finalizes a Revision, and publishes it. Publish is content-only and private. CLI publish prints the `private_url` (`/v/<artifactId>` clean viewer) as `View`; MCP publish returns the same `private_url` and omits management IDs. CLI JSON output carries diagnostic IDs and snapshot URLs for automation. Artifact lifetime comes from Workspace policy, not a CLI flag.

`private_url` is login-walled app navigation. A plain `curl` may receive the web app shell with a sign-in redirect state and HTTP 200; that does not prove the Artifact is publicly readable. Verify public/no-login handoff with a Share Link from `agent-paste set-visibility <artifact-id> unlisted`, or verify machine access through `agent_view_url` and the signed per-file `files[].url` entries.

A folder entrypoint is inferred from `index.html`, `index.md`, `README.md`, or the only file in the folder. Pass `--entrypoint` when that is not enough.

For an authenticated unlisted no-login link that follows later publishes, run `agent-paste set-visibility <artifact-id> unlisted` on the CLI, or MCP `set_visibility` with `visibility: "unlisted"`, to mint or reuse the Share Link and return `unlisted_url`. Accountless `--ephemeral` publish is the exception: it auto-creates that Share Link and returns `unlisted_url` immediately. The direct `usercontent.agent-paste.sh/v/...` URL points at one Revision, does not Live Update, and direct HTML opened there is inert raw byte delivery. The `private_url` clean viewer is the default Workspace view publish returns.

## Ephemeral fallback

```sh
npx @zaks-io/agent-paste publish ./report --ephemeral
```

`--ephemeral` self-provisions a short-lived Ephemeral Workspace, publishes once, and leads human output with `unlisted_url`, a working no-login script-disabled Share Link. Relay `unlisted_url` for immediate viewing and `claim_url` when the human wants to keep, own, or unlock interactivity. It ignores stored login, so use it only when auth is unavailable or explicitly skipped. Ephemeral is not the Free Plan: use it for non-interactive text, markdown, images, and static HTML/CSS. Unclaimed ephemeral HTML is script-disabled, so use authenticated publish for interactive work.

# CLI Reference

The CLI is the primary publish surface for humans, agents, and CI.

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

## Commands

| Command | Purpose |
| --- | --- |
| `agent-paste help publish` | Agent-oriented publish guide with mode choices, recipes, and JSON fields. |
| `agent-paste login` | Sign in through browser OAuth and store a scoped local credential. |
| `agent-paste logout` | Revoke the stored credential when possible, then remove it locally. |
| `agent-paste whoami` | Show the resolved Workspace, actor, and granted scopes. |
| `agent-paste publish <path>` | Upload files, publish a Revision, and print the result. Content-only and private. |
| `agent-paste pull <artifact-id> <path>` | Read one stored file's content back from an Artifact. |
| `agent-paste edit <artifact-id> <path>` | Apply literal find/replace edits to one stored file, then publish a new Revision under the same link. |
| `agent-paste set-visibility <artifact-id> <private|unlisted>` | Change visibility. `unlisted` returns `unlisted_url`; `private` revokes active Access Links. |
| `agent-paste version` | Print the CLI version baked into the package or binary. |
| `agent-paste upgrade [<tag>]` | Self-update a standalone binary install. |

## Auth checks

`agent-paste whoami` answers the auth state query. It exits `0` when signed out because the command ran successfully and returned a valid signed-out state. Agents and scripts should use `agent-paste whoami --json` and branch on `authenticated`, not on the process exit code.

## Publish flags

| Flag | Purpose |
| --- | --- |
| `--artifact-id <id>` | Publish a new Revision of an existing Artifact. |
| `--title <text>` | Set the display title. New Artifacts default to the file or folder name; revisions preserve the existing title unless this is explicit. |
| `--entrypoint <path>` | Choose the file opened first by viewers. |
| `--render-mode <mode>` | Override inferred mode: `html`, `markdown`, `text`, `image`, `audio`, or `video`. |
| `--ephemeral` | Restricted accountless fallback for non-interactive text/images/static output. Ignores stored login, disables scripts while unclaimed, and prints `unlisted_url` plus `claim_url`. |
| `--revision-id <id>` | With `pull`, read a specific Revision instead of the latest Published Revision. |
| `--edits <file>` | With `edit`, read the JSON edit array from a file instead of stdin. |
| `--json` | Emit pure JSON on stdout. Errors still go to stderr. |
| `--quiet` | Suppress human-readable stdout. |
| `--color` / `--no-color` | Force rich or plain output. Default: rich on a TTY, plain when piped. |

## Output

Publish is content-only and private. A successful CLI publish leads with `View`, the `private_url` (`/v/<artifactId>` clean viewer for the Workspace Member), then an `Update` line: the one command to revise this Artifact in place (`publish <path> --artifact-id art_...`). The `Update` line is the explicit revise handle on the human surface — Revision IDs, `revision_content_url`, and `agent_view_url` stay in the JSON output. Revising keeps the same link and live-updates pages already open; publishing again without the id makes a new Artifact on a new link.

```text
✓ Published "My Publication Title"

  View      https://app.agent-paste.sh/v/art_01H...
  Expires   2026-06-20
  Upload    3/3 uploaded, 0 reused · 42 KB sent, 0 B cached

  Update    npx @zaks-io/agent-paste publish ./report --artifact-id art_01H...
            (revises this Artifact; same link live-updates the open page)

  → open https://app.agent-paste.sh/v/art_01H...
```

> Do not verify Private Links with status code alone
> A `private_url` opens the app viewer for a signed-in Workspace Member. Plain HTTP clients can receive the app shell or sign-in redirect state with a 200 response; that does not make the Artifact reachable without login. Use `set-visibility <artifact-id> unlisted` for a no-login browser link, and use `agent_view_url` plus Agent View `files[].url` entries for machine verification.

> Authenticated unlisted sharing is a separate step
> Authenticated publish is content-only and private; `private_url` is the login-walled `/v/<artifactId>` clean viewer. When a human needs a no-login URL that follows later publishes, run `agent-paste set-visibility <artifact-id> unlisted`; it mints or reuses the one unlisted Share Link and returns `unlisted_url`. Accountless `--ephemeral` publish is the exception: it auto-creates that unlisted Share Link and returns `unlisted_url` immediately. `set-visibility <artifact-id> private` revokes active Access Links. `revision_content_url` is raw signed byte delivery for one Revision.

> Ephemeral output leads with the no-login link
> With `--ephemeral`, human-readable output leads with `unlisted_url`, the no-login script-disabled Share Link that works immediately. The `claim_url` is the keep/upgrade path for owning the Artifact and unlocking interactivity. Agents should relay `unlisted_url` for viewing and never relay `private_url` from an unclaimed ephemeral publish.

> Check auth before ephemeral
> Agents should run `agent-paste whoami --json` before using `--ephemeral`; it exits `0` either way, so check the JSON, not the exit code. If it reports you are signed in, publish normally. Ephemeral is fine for non-interactive text, markdown, images, and static HTML/CSS. It is wrong for interactive HTML/JS because scripts stay disabled while unclaimed; after claim, interactivity runs through the controlled Artifact Viewer.

## Pull and edit

`pull` reads one stored file back so an agent can inspect or edit against the current bytes. Plain `pull` writes the text body to stdout; `--json` adds metadata such as `sha256`, `size_bytes`, `is_binary`, and `body` when the file is UTF-8 text and within the inline size limit.

```sh
agent-paste pull art_01H... index.html > current-index.html
agent-paste pull art_01H... index.html --revision-id rev_01H... --json
```

`edit` applies the same literal find/replace shape as MCP `multi_edit`, then publishes a new Revision under the same stable Artifact link.

```sh
printf '[{"old_string":"old","new_string":"new"}]' |
  agent-paste edit art_01H... index.html --json

agent-paste edit art_01H... index.html --edits edits.json --json
```

Each `old_string` must match the current file exactly once unless `replace_all: true` is set. A non-matching or ambiguous edit fails loudly; pull the file first to get the exact base text.

## Retries and local exclusions

The CLI generates one idempotency key per publish and reuses it across automatic retries, so transient failures do not create duplicate Artifacts or Revisions.

Folder uploads exclude `.git/`, `.DS_Store`, `node_modules/`, `.env`, and `.env.*`. The exclusion list is intentionally not configurable.

# Artifact Model

Artifacts, Revisions, Access Links, and Agent View are the core handoff objects.

Human page: /docs/artifact-model
Markdown page: /docs/artifact-model.md

## Objects

| Object | Meaning |
| --- | --- |
| Workspace | The tenant that owns Artifacts, members, Plan, and Audit Events. |
| Artifact | A durable, addressable folder-like package containing one or more files. |
| Revision | An immutable saved state of an Artifact after publish. New publishes append Revisions. |
| Published Revision | The Revision currently visible through stable Artifact links. |
| Private Link | The login-walled clean viewer (`/v/<artifactId>`) for a Workspace Member; the `private_url` publish returns. |
| Artifact Console | The dashboard-only management page (`/artifacts/<id>`); never returned by publish. |
| Revision Content URL | A signed Content Origin byte URL for one exact Revision. It expires, does not Live Update, and direct HTML there is inert. |
| Access Link | A revocable grant family for unauthenticated read access. |
| Share Link | Access Link type that follows the latest Published Revision; created by `set-visibility unlisted`. |
| Revision Link | A snapshot Access Link pinned to one specific Revision. |
| Bundle | A downloadable archive generated from a complete Revision file tree. |

## IDs and handoff URLs

Publish creates stable Artifact and Revision IDs and is content-only and private. The default post-publish `View` (`private_url`) is the login-walled `/v/<artifactId>` clean viewer for a Workspace Member. Unlisted no-login handoff is `agent-paste set-visibility <artifact-id> unlisted` on the CLI, or MCP `set_visibility` with `visibility: "unlisted"`; it mints or reuses the one Share Link and returns `unlisted_url` opening the controlled Artifact Viewer. The direct `usercontent.agent-paste.sh/v/...` URL is the Revision Content URL for one exact Revision and is raw byte delivery, not the product viewer.

```text
art_01HZ8K2X9NPQR3VW7TYBE5MCDF
rev_01HZ8K2X9NPQR3VW7TYBE5MCDF
```

## Revisions and Live Updates

Publishing to an existing Artifact creates a new Published Revision. Old Revisions remain addressable through Revision Links while retained by the Workspace policy.

On Pro, Live Updates let already-open Artifact Viewers opened through Share Links or authenticated Private Links advance to the latest Published Revision without a manual reload. Revision Links and Revision Content URLs are pinned to one Revision and do not Live Update. Draft Revisions are never revealed.

## Agent View

Agent View is JSON for machines. It includes Artifact and Revision IDs, title, entrypoint, file metadata, signed per-file URLs, and Bundle Availability. It does not inline file bytes. Each file entry uses `files[].url` for the signed content URL, with `path`, `size_bytes`, `content_type`, and optional `sha256` beside it.

# Sharing and Access Links

Share human-readable viewers and machine-readable manifests without exposing credentials.

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

## Link types

| Link | Use |
| --- | --- |
| Access Link | Revocable grant family for unauthenticated read access. |
| Share Link | Access Link type that follows the latest Published Revision; created by `set-visibility unlisted`. |
| Revision Link | Snapshot Access Link pinned to one specific Revision. |
| Private Link | Login-walled clean viewer (`/v/<artifactId>`) for a Workspace Member; the `private_url` publish returns. |
| Artifact Console | Dashboard-only management page (`/artifacts/<id>`); never returned by publish. |
| Access Link Signed URL | URL minted from an Access Link. Returned as `unlisted_url` for a Share Link. |
| Revision Content URL | Direct signed `usercontent.agent-paste.sh/v/...` byte URL for one specific Revision; direct HTML there is inert. |
| Agent View URL | JSON manifest for agents, either authenticated or public through a signed token. |

## Signed URL shape

Access Link Signed URLs are shaped like `https://app.agent-paste.sh/al/{publicId}#{blob}`. The signature payload lives in the URL fragment so it is not sent to servers in normal HTTP requests.

The `publicId` identifies the link row. The fragment is the credential. Re-minting creates a fresh signed URL with a fresh expiration.

Use Access Link Signed URLs minted from Share Links only for explicit unlisted no-login handoff. They open the controlled Artifact Viewer and follow later publishes. Use Revision Links or Revision Content URLs only when the reader must see one exact Revision as raw bytes. Do not send a direct `usercontent` URL as the final live page.

## Create, mint, revoke, lockdown

Use the dashboard Access Links page or Artifact detail page to create links, reveal freshly minted signed URLs, revoke links, or engage Access Link Lockdown for an Artifact.

MCP can set visibility to `unlisted`, create Revision Links, list links, and revoke links for authenticated members. On the CLI, `agent-paste set-visibility <artifact-id> unlisted` creates or reuses the Share Link; `agent-paste set-visibility <artifact-id> private` revokes active Access Links. Publish itself is content-only and never creates a Share Link. Ongoing link listing and revocation stay in the dashboard or MCP.

> Revocation boundary
> Revoking an Access Link stops future resolves and deny-lists already minted content URLs for that link. Deleting an Artifact is separate and makes the Artifact inaccessible.

## Recipients

A Workspace Member opens the `private_url` clean viewer (`/v/<artifactId>`) by default. When a user explicitly asks for a shareable no-login page, run `agent-paste set-visibility <artifact-id> unlisted` on the CLI, or the MCP `set_visibility` tool with `visibility: "unlisted"`, to mint or reuse the unlisted Share Link and return `unlisted_url`. Use Agent View when an agent needs file trees, metadata, or signed per-file URLs.

# 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. The CLI provisions an Ephemeral Workspace, then publishes through the normal Upload Session flow.
3. Human-readable output leads with `unlisted_url`, a working no-login Share Link. Relay this link for immediate viewing, not the `private_url`.
4. A signed-in human opens the `claim_url` to keep, unlock interactivity, and move the Artifact into their Personal 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.

## After claim

Claiming reparents the Artifact into the signed-in member's Personal Workspace. The Artifact moves to the Free Plan limits unless the destination Workspace is already Pro.

# Dashboard

The dashboard is the human control plane for Workspaces, Artifacts, links, billing, and settings.

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

## Sign in

Open [app.agent-paste.sh](https://app.agent-paste.sh) or run `agent-paste login`. Both use WorkOS-backed browser auth.

## Pages

| Page | Purpose |
| --- | --- |
| `/dashboard` | Workspace overview, Usage Policy, recent Artifacts, and recent Audit Events. |
| `/artifacts` | Artifact list with status, pinning, Bundle state, Access Link Lockdown, and last publish time. |
| `/artifacts/{artifactId}` | Artifact detail, viewer, Revisions, Access Links, Bundle state, warnings, and delete action. |
| `/access-links` | Workspace-wide Access Link list and management. |
| `/keys` | Dashboard member credential list, create, and revoke controls. |
| `/audit` | Workspace Audit Event list. |
| `/settings` | Workspace name and default retention settings. |
| `/billing` | Plan, remaining writes, Checkout, Portal, and invoices. |

## Claiming ephemeral work

The claim page accepts `/claim#<token>`. It requires a signed-in human and promotes the Ephemeral Workspace's Artifact into that member's Personal Workspace.

# MCP Server

Hosted agents without CLI access can publish, inspect, revise, and share text Artifacts over OAuth-only MCP.

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

## When to use MCP

Use MCP when an agent runs inside a hosted tool that can connect to remote MCP servers but cannot install npm packages, spawn a CLI, or use a local keychain.

MCP is not a weaker side channel. It is the hosted-agent surface for publishing text Artifacts, reading Agent Views, adding Revisions, and explicitly managing Share Links and snapshot links without shell access.

## Endpoint

Production MCP runs at `https://mcp.agent-paste.sh`. Opening `GET /` returns endpoint metadata for humans and agents. Protocol calls use `POST /` with Streamable HTTP JSON-RPC and an OAuth bearer token. Protected Resource Metadata is at `/.well-known/oauth-protected-resource`; the root OAuth resource is `https://mcp.agent-paste.sh/`.

MCP verifies a WorkOS-issued OAuth bearer token and forwards authenticated calls to `api` and `upload` over service bindings. Dashboard cookies and local CLI credentials do not authenticate MCP calls.

Connect `https://mcp.agent-paste.sh` in the host, complete OAuth, then run `whoami` first. The WorkOS user must already belong to a Workspace, which dashboard sign-in or `agent-paste login` creates.

## Capability scopes

WorkOS AuthKit tokens carry standard OAuth scopes. agent-paste derives capabilities from the authenticated Workspace Member in `api`, using one shared scope vocabulary: `read` and `publish` (`admin` is dashboard-only and no MCP tool needs it).

| Scope | Grants | Tools |
| --- | --- | --- |
| `read` | View your own Artifacts and links | `whoami`, `list_artifacts`, `read_artifact`, `read_file`, `list_revisions`, `list_access_links` |
| `publish` | Change your own content and manage visibility/access links | `publish_artifact`, `add_revision`, `multi_edit`, `delete_artifact`, `update_display_metadata`, `set_visibility`, `create_revision_link`, `revoke_access_link` |

## Tools

| Tool | Purpose |
| --- | --- |
| `whoami` | Return authenticated member, Workspace, and derived scopes. |
| `publish_artifact` | Publish a NEW text-only Artifact (new private_url). Content-only and private. To change published work, use add_revision instead. |
| `add_revision` | Revise an EXISTING Artifact: pass its artifact_id to publish a new Revision. Same stable private_url; live-updates open viewers. Use this to change published work, not publish_artifact. |
| `multi_edit` | Edit one stored file with literal find/replace, then publish the result as a new Revision under the same Artifact. |
| `list_artifacts` | List Artifacts in the Workspace. |
| `read_artifact` | Read latest Agent View for an Artifact. |
| `read_file` | Read one stored file's plaintext body or metadata so an agent can edit against the current bytes. |
| `list_revisions` | List Revisions for an Artifact. |
| `delete_artifact` | Delete an Artifact. |
| `update_display_metadata` | Update an Artifact display title. |
| `set_visibility` | Set visibility. `private` revokes active Access Links; `unlisted` returns `unlisted_url`. |
| `create_revision_link` | Create and mint a snapshot Access Link for a specific Revision. |
| `list_access_links` | List Share Links and Revision Links for an Artifact. |
| `revoke_access_link` | Revoke a Share Link or Revision Link. |

## Limits

The MCP publish tools are text-only. Binary uploads, multi-file folder uploads, and standalone Bundle downloads stay in the CLI. Workspace settings, billing, and lockdown controls stay in the dashboard.

`publish_artifact`, `add_revision`, and `multi_edit` are content-only and private: they take no visibility input and return a single `private_url` (the login-walled `/v/<artifactId>` clean viewer for the Workspace Member), with no `shared` field. To make an Artifact reachable without login, call `set_visibility` with `visibility: "unlisted"`; it mints or reuses the one Share Link that follows the latest Revision and returns `unlisted_url`. To remove no-login access, call `set_visibility` with `visibility: "private"`. To change a published Artifact, call `add_revision` or `multi_edit` with its `artifact_id` rather than `publish_artifact`: the `private_url` is stable and already-open viewers live-update to the new Revision, whereas a second `publish_artifact` mints a separate Artifact on a new link. Artifact IDs, Revision IDs, and content URLs are available through the read/list/link tools. The tools also accept optional idempotency keys; when omitted, the server derives stable keys from the OAuth subject, JSON-RPC id, and tool name.

Artifact lifetime follows Workspace Auto Deletion policy. MCP callers do not choose TTL.

# Limits and Retention

Billing-enabled limits keep handoffs useful without turning the service into permanent storage.

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

## Plan limits

| Limit | Ephemeral | Free | Pro |
| --- | --- | --- | --- |
| Daily new Artifacts | 20 | 100 | 2000 |
| File size cap | 10 MB | 10 MB | 25 MB |
| Artifact size cap | 25 MB | 25 MB | 100 MB |
| Bundle size cap | 25 MB | 25 MB | 100 MB |
| Default TTL | 24h | 3d | 30d |
| Max TTL | 24h | 7d | 90d |
| Live Artifacts | low-cap unclaimed Workspace | 50 | 1000 |
| Live Updates | No | No | Yes |

## Shared limits

- 100 files per Revision.
- 100 lifetime published Revisions per Artifact.
- 60 authenticated requests per minute per actor.
- 300 authenticated requests per minute per Workspace.
- Pinned Artifact cap: 50 per Workspace.

## Retention

Every Artifact has Auto Deletion. Free Workspaces default to 3 days and can choose up to 7 days. Pro Workspaces default to 30 days and can choose up to 90 days. Ephemeral Artifacts auto-delete after 24 hours unless claimed.

Pinned Artifacts are exempt from Auto Deletion while they remain pinned, subject to the Workspace cap. Non-current Revisions are retained according to policy and Revision links stop working after a retained Revision is removed.

## Write allowance

The daily allowance counts new Artifacts. New Revisions of an existing Artifact do not count against the daily new-Artifact allowance, but each Artifact still has a 100 lifetime Revision ceiling.

# Safety and Content Isolation

agent-paste treats uploaded work as untrusted content and isolates serving from control-plane auth.

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

## What not to publish

Published Artifacts are private to the Workspace by default. When you explicitly create an Access Link Signed URL, anyone with that URL can read the files until the Artifact or link expires, is revoked, or is deleted. Treat shared links as sensitive.

Do not upload secrets or other people's data. In particular:

- Tokens, passwords, private keys, `.env` files, or any other credential.
- Personal or customer data you are not authorized to share or required to protect.
- Anything you would not be comfortable handing to whoever holds the link.

If you publish a secret by mistake, rotate it and delete or revoke the Artifact. Deletion can make content unreachable before every backup, cache, or queued cleanup job has finished.

## Origin boundary

Published files are served from `usercontent.agent-paste.sh`, not the dashboard or API origin. R2 stays private. Clients receive signed content URLs, never direct storage URLs. The content origin is byte delivery; direct top-level HTML there is inert and unbranded.

## Response policy

The content origin verifies signed tokens, expiration, scope, denylist state, and requested path. Authorization failures return generic not found responses.

Untrusted content responses carry CSP, HSTS, X-Content-Type-Options, frame protections, Referrer-Policy, and permissions restrictions. Interactive HTML execution is allowed only inside the controlled Artifact Viewer iframe; direct `usercontent` HTML gets `script-src 'none'`. SVG receives a stricter CSP.

## Ephemeral script policy

Unclaimed ephemeral HTML may contain scripts, but scripts do not execute. Static markup and CSS still render. After a human claims the Artifact into a regular Workspace, newly minted viewer URLs may use the claimed Workspace execution policy, but interactive HTML still runs only inside the controlled Artifact Viewer iframe.

## Revocation

agent-paste does not inspect or certify uploaded content as safe. Access Links can be revoked, and abusive content can be disabled without exposing private storage URLs.

## Secret handling

- Stored credentials are non-recoverable after creation.
- Claim Tokens ride the URL hash and are stored hashed.
- Signed Access Link credentials live in URL fragments.
- Tokens, signed URLs, and credential secret material must not be logged.