# 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 API Keys.
- [Ephemeral Publish and Claim Tokens](/docs/ephemeral.md) - Restricted accountless publish for when no login or API Key is available.
- [Dashboard](/docs/dashboard.md) - The dashboard is the human control plane for Workspaces, Artifacts, links, keys, billing, and settings.
- [Billing and Plans](/docs/billing.md) - Hosted billing is enabled: your Plan sets write allowance, retention, caps, and Live Updates.
- [REST API](/docs/rest-api.md) - Use REST when the CLI is the wrong runtime for your agent or service.
- [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` when Node.js 24 is available, or install the standalone binary when you want one file with no Node runtime.

```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, mints a scoped API Key, and stores it in your OS keyring when available.

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

For CI or a headless agent, set `AGENT_PASTE_API_KEY`. The CLI never accepts secrets as flags. If both a stored login and `AGENT_PASTE_API_KEY` exist, the environment key wins.

Agents should run `agent-paste whoami` before falling back to accountless publish. A successful `whoami` means use normal authenticated publish, not `--ephemeral`.

## 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, publishes it, and returns `artifact_id`, `artifact_url`, `revision_content_url`, and `agent_view_url`. Artifact lifetime comes from Workspace policy, not a CLI flag.

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 a stable link that follows later publishes, use the Artifact URL. The direct `usercontent.agent-paste.sh/v/...` URL points at one Revision and does not Live Update.

## Ephemeral fallback

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

`--ephemeral` self-provisions a short-lived Ephemeral Workspace and key, publishes once, and prints a one-time Claim Token as `/claim#<token>`. It ignores stored login and `AGENT_PASTE_API_KEY`, 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 login` | Mint a browser-OAuth API Key with `publish` and `read` scopes. |
| `agent-paste logout` | Revoke the stored API Key when possible, then remove local credentials. |
| `agent-paste whoami` | Show the resolved Workspace, actor, and granted scopes. |
| `agent-paste publish <path>` | Upload files, publish a Revision, and print the result. |
| `agent-paste version` | Print the CLI version baked into the package or binary. |
| `agent-paste upgrade [<tag>]` | Self-update a standalone binary install. |

## Publish flags

| Flag | Purpose |
| --- | --- |
| `--artifact-id <id>` | Publish a new Revision of an existing Artifact. |
| `--title <text>` | Set the display title. Defaults to the file or folder name. |
| `--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 login/key, disables scripts until claimed, and prints a one-time claim link. |
| `--json` | Emit pure JSON on stdout. Errors still go to stderr. |
| `--quiet` | Suppress human-readable stdout. |

## Output

A successful publish returns `artifact_id`, `revision_id`, `title`, `artifact_url`, `revision_content_url`, `agent_view_url`, `expires_at`, and `bundle`. `artifact_url` is the app-origin live viewer for the Artifact. `revision_content_url` is a signed Content Origin URL for this exact Revision and does not Live Update. `agent_view_url` returns machine-readable Agent View JSON.

```json
{
  "artifact_id": "art_01H...",
  "revision_id": "rev_01H...",
  "title": "My Publication Title",
  "artifact_url": "https://app.agent-paste.sh/artifacts/art_01H...",
  "revision_content_url": "https://usercontent.agent-paste.sh/v/...",
  "agent_view_url": "https://api.agent-paste.sh/v1/public/agent-view/...",
  "expires_at": "2026-06-20T00:00:00.000Z",
  "bundle": {
    "status": "pending",
    "retry_after_seconds": 5
  }
}
```

> Artifact URL is the live viewer
> When a human should keep one URL open while an agent publishes more Revisions, return `artifact_url`. Use public sharing only when the viewer needs unauthenticated access; that access belongs in a separate Share URL.

> Check auth before ephemeral
> Agents should run `agent-paste whoami` before using `--ephemeral`. If `whoami` succeeds, 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 until the Artifact is claimed.

## 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, API Keys, 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. |
| Artifact URL | The app-origin live viewer for an Artifact. It resolves to the latest Published Revision. |
| Revision Content URL | A signed Content Origin URL for one exact Revision. It expires and does not Live Update. |
| Access Link | A revocable signed URL for a Share Link or a Revision Link. |
| Share Link | An Access Link that resolves to the latest Published Revision of an Artifact. |
| Bundle | A downloadable archive generated from a complete Revision file tree. |

## IDs and handoff URLs

Publish returns stable Artifact and Revision IDs plus an Artifact URL for the live viewer. The direct `usercontent.agent-paste.sh/v/...` URL is the Revision Content URL for one exact Revision.

```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 URL, Private Link, or Share Link viewers 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.

# Sharing and Access Links

Share human-readable viewers and machine-readable manifests without exposing API Keys.

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

## Link types

| Link | Use |
| --- | --- |
| Private Link | Authenticated dashboard viewer for Workspace members. |
| Share Link | Access Link for the latest Published Revision of an Artifact. |
| Revision Link | Access Link pinned to one specific Revision. |
| Artifact URL | App-origin live viewer for the latest Published Revision of an Artifact. |
| Share URL | Public access-bearing URL for an Artifact viewer. |
| Revision Content URL | Direct signed `usercontent.agent-paste.sh/v/...` content URL for one specific Revision. |
| Agent View URL | JSON manifest for agents, either authenticated or public through a signed token. |

## Signed URL shape

Access Link 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 Artifact URLs for stable human handoff. Use Share URLs when the same viewer needs public access. Use Revision Links or Revision Content URLs only when the reader must see one exact Revision.

## 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 create Share Links and Revision Links, list links, and revoke links for authenticated members. The CLI focuses on publish and does not manage Access Links directly.

> 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 human opens the Access Link in a browser. An agent should prefer Agent View when it needs file trees, metadata, or signed per-file URLs.

# Ephemeral Publish and Claim Tokens

Restricted accountless publish for when no login or API Key is available.

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

## Use authenticated publish first

Agents should run `agent-paste whoami` before choosing `--ephemeral`. If `whoami` succeeds, publish normally without `--ephemeral`. If it fails and the user can interact, run `agent-paste login` first. Use `--ephemeral` only when no login or `AGENT_PASTE_API_KEY` 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 until the Artifact is claimed. 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 and short-lived API Key, then publishes through the normal Upload Session flow.
3. The publish result works immediately and includes a one-time claim link shaped `https://app.agent-paste.sh/claim#ap_ct_...`.
4. A signed-in human opens the claim link to 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 until claimed |

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 until the Artifact is claimed and new content URLs are minted from a claimed Workspace. 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 or public share 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, keys, 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. The CLI login mints a scoped API Key for local use.

## 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` | Create, reveal once, list, and revoke API Keys. |
| `/audit` | Workspace Audit Event list. |
| `/settings` | Workspace name and default retention settings. |
| `/billing` | Plan, remaining writes, Checkout, Portal, and invoices. |

## API Keys

Dashboard-created keys are shown once and cannot be recovered later. Store them where your agent or CI can read `AGENT_PASTE_API_KEY`. Keys are capped at `publish` and `read`, never member-only admin scopes.

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

# Billing and Plans

Hosted billing is enabled: your Plan sets write allowance, retention, caps, and Live Updates.

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

## Plans

| Plan | Daily new Artifacts | File cap | Artifact and Bundle cap | TTL | Live Artifacts | Live Updates |
| --- | --- | --- | --- | --- | --- | --- |
| Ephemeral | 20 | 10 MB | 25 MB | 24h auto-delete | low-cap unclaimed Workspace | No |
| Free | 100 | 10 MB | 25 MB | 3d default, 7d max | 50 | No |
| Pro | 2000 | 25 MB | 100 MB | 30d default, 90d max | 1000 | Yes |

Shared caps: 100 files per Revision, 100 lifetime published Revisions per Artifact, 60 actor requests per minute, and 300 Workspace burst requests per minute.

## Upgrade

Open `/billing` in the dashboard and choose the Pro interval. The dashboard creates a Stripe Checkout session and redirects you to Stripe.

After a successful Checkout return, the dashboard activates Pro synchronously, refreshes the billing cache, and shows the updated Plan. Stripe webhooks and daily reconciliation keep local entitlement state converged after that.

## Manage subscription and invoices

The billing page can open Stripe Customer Portal for subscription management and cancellation. It also lists Stripe invoices with hosted invoice and PDF links when Stripe provides them.

Reads are always free. Billing changes write allowance and feature limits; it does not meter recipients opening an Artifact or Access Link.

## Subscription statuses

Stripe `active`, `trialing`, and `past_due` subscriptions map to Pro. Canceled, unpaid, incomplete, expired, paused, or missing subscriptions map to Free.

# REST API

Use REST when the CLI is the wrong runtime for your agent or service.

Human page: /docs/rest-api
Markdown page: /docs/rest-api.md

## Hosts

| Host | Purpose |
| --- | --- |
| `https://api.agent-paste.sh` | Control plane, Agent View, web API, ephemeral provision/claim, billing routes, and OpenAPI. |
| `https://upload.agent-paste.sh` | Upload Sessions and signed file PUT URLs. |
| `https://usercontent.agent-paste.sh` | Signed content and Bundle reads from isolated untrusted-content origin. |
| `https://app.agent-paste.sh` | Dashboard, Access Link viewer, claim page, and billing UI. |
| `https://mcp.agent-paste.sh` | OAuth-only MCP transport. |

## Authentication

API clients send `Authorization: Bearer ap_pk_...`. Use dashboard-created keys or the key minted by `agent-paste login`. Public Agent View, Access Link resolve, signed content, and signed Bundle URLs use signed tokens instead of API Keys.

## Publish flow

1. Create an Upload Session with file metadata and an `Idempotency-Key`.
2. PUT each file to the returned signed upload-worker URL.
3. Finalize the Upload Session with an `Idempotency-Key`.
4. Publish the finalized Revision. The response includes human and agent URLs.

## Common routes

| Route | Use |
| --- | --- |
| `GET /v1/whoami` | Verify API Key identity and Workspace. |
| `GET /v1/usage-policy` | Read effective limits for the caller's Workspace. |
| `GET /v1/artifacts/{id}/agent-view` | Read latest authenticated Agent View. |
| `GET /v1/artifacts/{id}/revisions/{revision_id}/agent-view` | Read Revision-pinned authenticated Agent View. |
| `GET /v1/public/agent-view/{token}` | Read public signed Agent View. |
| `POST /v1/ephemeral/provision` | Provision an Ephemeral Workspace and short-lived key. |

- [API OpenAPI](https://api.agent-paste.sh/openapi.json)
- [Upload OpenAPI](https://upload.agent-paste.sh/openapi.json)
- [Content OpenAPI](https://usercontent.agent-paste.sh/openapi.json)

# 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 a core agent surface for publishing text Artifacts, reading Agent Views, adding Revisions, and managing Share Links or Revision Links without shell access.

## Endpoint

Production MCP runs at `https://mcp.agent-paste.sh`. The transport endpoint is `POST /` using Streamable HTTP JSON-RPC. Protected Resource Metadata is at `/.well-known/oauth-protected-resource`; the root OAuth resource is `https://mcp.agent-paste.sh/`.

MCP does not accept API Keys or dashboard cookies. It verifies a WorkOS-issued OAuth bearer token and forwards authenticated calls to `api` and `upload` over service bindings.

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 MCP capabilities from the authenticated Workspace Member in `api`: `read`, `write`, and `share`.

| MCP scope | Backed by | Typical tools |
| --- | --- | --- |
| `read` | member `read` | `whoami`, `list_artifacts`, `read_artifact`, `list_revisions` |
| `write` | member `publish` | `publish_artifact`, `add_revision`, `delete_artifact`, `update_display_metadata` |
| `share` | member `admin` | `create_share_link`, `create_revision_link`, `list_access_links`, `revoke_access_link` |

## Tools

| Tool | Purpose |
| --- | --- |
| `whoami` | Return authenticated member, Workspace, and derived scopes. |
| `publish_artifact` | Publish a new text-only Artifact and return its Artifact URL. |
| `add_revision` | Add and publish a new text-only Revision and return its Artifact URL. |
| `list_artifacts` | List Artifacts in the Workspace. |
| `read_artifact` | Read latest Agent View for an Artifact. |
| `list_revisions` | List Revisions for an Artifact. |
| `delete_artifact` | Delete an Artifact. |
| `update_display_metadata` | Update an Artifact display title. |
| `create_share_link` | Create and mint a Share Link for the latest Revision. |
| `create_revision_link` | Create and mint a Revision 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, standalone Bundle downloads, workspace settings, billing, and lockdown controls stay in CLI, REST, or dashboard surfaces.

`publish_artifact` and `add_revision` 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 meant to be shared. Anyone with a valid Artifact URL or Access Link can read the files until the Artifact or link expires, is revoked, or is deleted. Treat everything you publish as readable by others.

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

- API keys, 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.

## 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. 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 content URLs use the claimed Workspace execution policy.

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

- API Key secrets are shown once and stored hashed server-side.
- Claim Tokens ride the URL hash and are stored hashed.
- Signed Access Link credentials live in URL fragments.
- Tokens, signed URLs, and API Key secret material must not be logged.