llms.txt@apps/web/public · git:20261001.c7ef089 · 2026-10-01 · sha256 19b8e67692ec3ee1

llms.txt@apps/web/public git:20261001.c7ef089A

Immutable. This exact content never changes and is served at /api/v1/blob/19b8e67692ec3ee1.

# 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`: an agent's key, from the `agents` tool
when the agent is created, or from the agent's page in Derive (its creator or a workspace owner
can replace it on the Settings tab).

```
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":

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 (seventeen): list_workspaces, find, read, catch_up, clear_queue, comment,
stage, publish, checkpoint, browse_library, organize, shelve, agents, ask, jobs, pull,
derive_code. `derive_code` is present only where the instance runs a code sandbox;
`list_workspaces` reports the live list.

- list_workspaces: inspect and route across granted workspaces, and list the tools served now
- find: browse or search artifacts
- 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
- clear_queue: clear handled items off the work queue that catch_up returned
- 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
- checkpoint: save compact, resumable working state
- browse_library, organize, shelve: browse tags and collections, tag and collect, retire or delete
- agents: list, create, update, or delete agents (create returns the agent's key and, for an owner machine, its runner command)
- ask: give an agent work, or follow up on one of its jobs; waits a bounded time for it to settle
- jobs: list or inspect jobs; cancel, retry, or answer one that needs you
- pull: run an owner-machine agent from this session: claim its jobs, then report each one
- derive_code: chain several read-only calls (searches, reads) in one sandboxed script

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

Resources: derive://skills lists the core skills: loop, finding, publishing, decks,
dynamic-data, latex, assets, bundles, workflows, agents, papers, checkpoint, organize,
sources, helping. Read one as derive://skills/<name>. The stdio server exposes
derive://guide instead.

## Agents

An agent is a named worker in a workspace: an instructions page, the sources it may use, a
model account, and a machine. Each piece of work it does is a job (one ask, one scheduled run,
or one graph), with a transcript; a job the CLI runner does also leaves a report page, private
to the workspace. A job that needs a person stops at `needs_you` and shows in their Inbox.

- Machine `owner`: a person's computer running `derive runner serve --agent <id>`. With no model
account stored in Derive, it uses the Claude Code or Codex login already on that machine.
- Machine `derive`: a Derive sandbox per agent that keeps its files between jobs. Only in
workspaces with Derive machines turned on; it needs a stored model account.

Create agents over MCP with `agents` (read derive://skills/agents first). A workflow is an
agent whose instructions page holds a `derive.workflow/v1` definition; Derive walks it
step by step (derive://skills/workflows).

## 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, and runs agent jobs: on the agent
owner's own machine, or on a Derive machine where a workspace has them. Do not use it for
general 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)