llms.txt@apps/web/public git:20260817.af7f583A

Immutable. This exact content is served forever at /api/v1/blob/3a52fc0906f866a1.

# Derive

> Keep, share, and improve agent-made pages and documents. Each artifact has a lasting URL, version history, and comments on 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. Proposals and formal review are available when permissions or a decision require them.

Fair Source and self-hostable (Docker, Fly.io, Railway, Render, Cloudflare Workers). Hosted tier at derive.to. 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 at `<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
POST   /v1/artifacts/:id/proposals             propose a candidate version for human approval
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 last human-approved version when one exists
(a proposal or review approval sets it); until a skill is ever approved, it serves
current. `?v=approved` on the content API resolves the same rule.

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)