llms.txt@apps/web/public git:20260823.ebcde54A

Immutable. This exact content is served forever at /api/v1/blob/0b6ff2ba3c4a608e.

# Derive

> Publish AI-built artifacts (HTML pages, Markdown docs, and slide decks) with a permanent URL, version history, and comments anchored to exact text.

## What it is

Derive is a workspace for work made with agents. Publish to a lasting URL, keep each revision,
comment on exact text with W3C TextQuoteSelector, edit directly, and control who can read or
change the work. Review rounds are there when a decision needs a named look: the reviewer
answers in comments and sends the work back with a note.

Fair Source and self-hostable (Docker, Fly.io, Railway, Render, Cloudflare Workers). The reference deployment is derive.to; a self-hosted instance serves the same API at its own origin. The FSL license converts each release to Apache-2.0 after two years.

## Artifact types

- Markdown (.md): rendered prose, task lists, tables, fenced code blocks
- HTML (.html): the page itself, sandboxed in an opaque origin with CSP
- HTML deck: HTML with <section class="slide"> elements, gets nav + present mode automatically via the derive-deck postMessage protocol

## Anonymous drafts

The zero-setup path. One HTTP call, no credentials:

```
POST /v1/drafts    multipart: file (one .html/.md, or a .zip site), optional title
```

Returns `draft_url` (live immediately, on the instance's usercontent domain; on
derive.to that is `<id>.derive.page`), `claim_url`, and
`expires_at` (72h). Report all three to the user: the draft expires unless they open
the claim link (sign in, one click) to keep it as a permanent versioned artifact.
The draft URL then redirects to the permanent home. The secret URL is the only
access (view-by-link, unlisted, noindex): don't put secrets in a draft. Drafts can't
be revised. Create a new one, or claim it before revising through MCP.

## Reading a shared artifact URL (no token needed)

Every `/artifacts/<ref>` share URL serves an agent-readable markdown projection of the
document: request the URL with `Accept: text/markdown`, or append `.md` to it
(`/artifacts/<ref>.md`, also `<ref>@vN.md` for a pinned version). Anonymous access works
whenever the link itself is viewable (a password-locked link must be unlocked on the web
page first); pinned versions other than the current one need a signed-in reader unless
the artifact enables public history. Without the header or suffix the URL serves the web
app's HTML shell, whose content loads client-side.

## Key API endpoints

All requests use `Authorization: Bearer $DERIVE_TOKEN` (static agent token from Settings > Agents).

```
POST   /v1/artifacts                           publish new artifact (multipart: file, title, visibility)
POST   /v1/artifacts/:id/versions              publish new version of existing artifact
GET    /v1/artifacts/:id                       artifact metadata + version list
GET    /v1/artifacts/:id/content?v=N           source read-back (current version by default)
GET    /v1/artifacts/:id/comments?state=open   comment threads
GET    /v1/artifacts/:id/diff?from=1&to=2      line diff between versions
GET    /raw/:id/v/:n/index.html                permanent artifact URL (immutable, cacheable)
```

Access on create uses three independent fields. Omitted fields use the workspace default;
the factory default is the "team draft":

- workspace_access: none | member. Sets whether workspace members can access it at their seat role.
- link_role: none | viewer | commenter | editor. Sets the access granted to anyone holding the URL.
- listed: none | workspace | public. Sets where the artifact appears for discovery; it grants no access.

Plus password (locks the world link; only meaningful with link_role != none). The legacy
`visibility` param (public | link | org | password) is still accepted and mapped.

## MCP server

Prefer the remote OAuth server at `https://derive.to/mcp` (or `<instance>/mcp`).
The local compatibility server is `npx -y @derive-to/mcp` and shares `derive login`.

Skills: `read("derive://skills")` returns the catalog (core skills plus the connected
workspace's own team skills); read one with `derive://skills/<name-or-short-id>`.
Reading a skill artifact by short id returns its SKILL.md body with the bundle's
files listed. Skill delivery serves the artifact's current version.

Capture: `GET /v1/artifacts/:id/save-as-skill?threadId=...` returns a prompt that turns
a review correction into a workspace skill (read the thread, dedup against the catalog,
publish live, link back); POST delivers the same instruction to a registered agent's
inbox.

Remote tools (ten): find, read, catch_up, comment, stage, publish, organize,
checkpoint, use, list_workspaces.

- find: browse or search artifacts and discover askable workspace contexts
- read: read an artifact's content by short id; bundles take a section (page path), any read takes a version for history
- catch_up: an artifact's review/change state, or the registered agent's queued work when called without a short id
- comment: leave feedback, reply (reply_to), anchor to a quote, resolve/reopen (set_state)
- stage: upload large documents or bundles out of band; for an image/font, mint an asset upload URL, POST raw bytes, then use the returned permanent url or bundle ref in publish
- publish: create or revise with edits/content/files; addresses resolves threads; request_review opens a review round
- organize: manage tags and collections
- checkpoint: save compact, resumable working state
- use: ask a workspace context or resume its session
- list_workspaces: inspect and route across granted workspaces

The stdio compatibility server exposes eight tools: list_workspaces, list_artifacts,
search, read, catch_up, comment, organize, publish.

Resources: derive://skills/publishing, /assets, /loop, /contexts, /checkpoint, /organize.
The stdio server also exposes derive://guide.

## Updating existing work

1. catch_up -> what changed since `since_version`, plus open feedback
2. read -> the current content, a bundle page, or a past version
3. comment -> reply, resolve, or reopen a thread when needed
4. publish with addresses: [threadIds] -> same URL, new version, addressed threads closed atomically

## Deployment tiers

- Lite: docker compose -f deploy/compose.yml up -d (SQLite + local blobs)
- Node Basic: add DATABASE_URL (Postgres) + OBJECT_STORE_URL (S3/R2)
- Node Scale: multiple containers for throughput (realtime is per-instance on Node; use Cloudflare for cross-instance realtime)
- Cloudflare Basic: Workers + D1 + R2 + Durable Objects (wrangler deploy)
- Cloudflare Scale: Workers + Postgres + R2 + Durable Objects

Key env vars: BASE_URL, DERIVE_AUTH_SECRET (openssl rand -hex 32), DERIVE_TOKEN

## Agent discovery

- /skill.md: the Derive agent skill, including when to use it, the tools, and the workflow
- /.well-known/agent.json: machine-readable capability manifest for this instance
- /openapi.json: the OpenAPI spec; /docs is its reference UI
- https://docs.derive.to/: human documentation; /examples has live artifact examples and source
- /llms-full.txt: the long-form version of this file

## Scope and drift

- Derive hosts documents, pages, and versioned artifacts. It does not run compute. Do not use it for
  server-side code execution, general-purpose data storage, secrets, or app backends.
- If this file and the live API disagree, trust the live API: fetched copies go stale.
  Re-read /skill.md or /docs before answering capability questions.

## Links

- GitHub: https://github.com/derive-to/derive
- Deployment guide: https://docs.derive.to/self-hosting/configuration/
- MCP skill: packages/mcp/SKILL.md (also served at /skill.md and as derive://guide)