OpenArtifacts publishes rendered HTML at a stable link and preserves every update as an immutable version. Publishers use an authenticated HTTP API; readers open a public document without an account, and a publisher can instead share a document only with people they invite, who sign in to open it. The Worker stores document bytes in Cloudflare R2 and ownership, version, deletion, and sharing metadata in D1.

It is a small API-first publishing service with inline comments on a quoted passage.

What works today

• Publish rendered HTML. Send a complete HTML document and get a link. The

• Keep one stable link. Every push creates a new version. The shared link

• Read without signing in. Publishing needs a bearer key. Reading a public

• Share privately. Set a document to "Only those invited" and add people by

• Comment on a passage. The owner gives named people Can comment (a paid-plan

• Keep pages out of search results. Serving responses carry noindex

• Run interactive documents. Scripts, charts, and simulations work. Pages

• List and unshare documents. Deleting destroys the stored files and leaves

• Bound abuse. Hosted free accounts get three live documents, six

Use from an agent

Install the CLI and shared skill into detected Claude Code, Codex, OpenCode, and pi installations:

npx openartifacts install

Hermes Agent needs only its native skill install:

hermes skills install https://cdn.jsdelivr.net/npm/openartifacts@latest/skill/openartifacts/SKILL.md

Hermes security-scans the skill and can refresh it later with hermes skills update. The skill uses an installed openartifacts command when available and falls back to npx otherwise. Node.js 20+ and npm are required.

The first publish opens a browser approval and stores the resulting token without printing it. Later publishes of the same local file update its existing document. Set OPENARTIFACTS_API_HOST for a self-hosted deployment, or provide an opaque credential through OPENARTIFACTS_TOKEN in a non-interactive session.

Vision

OpenArtifacts is an agent-first medium for publishing and reading webpages and other artifacts. It is designed for groups of humans and agents to iterate on the same page and converge on a shared result.

| Goal | Status | | --- | --- | | Agent-first publishing and reading | Available today | | Immutable versions and pinned version links | Available today | | Public sharing | Available today | | Self-hosting | Available today | | Private sharing (invite people by email; paid plans) | Available today | | Inline comments and replies (quote-anchored, humans and agents; paid plans) | Available today | | Version-history browser, visual diffs, and rollback UI | Roadmap |

Run locally

Requires Node.js 22 or newer. Local development uses the real Workers runtime with local R2 and D1 data, but needs no Cloudflare account.

npm install
npm run typecheck
npm test
Create the local schema and one local publisher.
npx wrangler d1 migrations apply DB --local
KEY=local-development-key
HASH=$(printf '%s' "$KEY" | shasum -a 256 | cut -d' ' -f1)
npx wrangler d1 execute DB --local --command \
  "INSERT OR REPLACE INTO publishers (key_hash, owner, plan, validated_at)
   VALUES ('$HASH', 'local-owner', 'plus', $(($(date +%s) * 1000)))"
npm run dev

In another terminal, exercise the whole publish, read, list, and delete path:

OPENARTIFACTS_LICENSE_KEY=local-development-key \
  scripts/smoke.sh http://127.0.0.1:8787

local-development-key is deliberately easy to copy and is only for local development. Use a generated high-entropy key for any internet-facing deployment.

Self-host on Cloudflare

How it fits together

One Cloudflare Worker runs the backend. A Worker is a serverless application: Cloudflare runs its code when requests arrive and manages the servers and scaling. The API and public document hostnames reach the same Worker, but expose different operations.

flowchart TD
    Publisher["CLI, agent, or other API client"] -->|"Publish, update, list, unshare"| API["API hostname<br/>api.example.com"]
    Reader["Reader's browser"] -->|"Open a public link"| Serving["Document hostname<br/>exampleusercontent.net"]
subgraph Account["Your Cloudflare account"]
        API --> Worker["One OpenArtifacts Worker<br/>Authenticate publishers, enforce limits,<br/>manage and serve documents"]
        Serving --> Worker
        Worker --> DB[("D1 database<br/>Ownership and version records,<br/>accounts, tokens, and quotas")]
        Worker --> Files[("R2 storage<br/>Published HTML versions")]
    end

D1 and R2 keep the persistent data; they are storage services, not additional Workers. Use a separate registrable domain for document HTML, not just another subdomain of your API's domain. Readers of public documents need no account, and the document host does not expose the publishing API.

This deployment uses your own Cloudflare resources. It does not require the OpenArtifacts hosted website, a Copilot subscription, or a billing service. The setup below uses a self-managed publisher key; browser sign-in is optional and requires separate OAuth configuration.

Set up your deployment

You need a Cloudflare account with Workers, R2, and D1, plus two domains added to that account:

• an API hostname on your brand domain; and
• a separate registrable domain for untrusted document HTML.

Choose your own account limits with PLAN_LIMITS and DEFAULT_PLAN in Worker vars; the checked-in values are the hosted free/paid policy. Without an override, the built-in map has one free plan: 3 documents, 6 pushes/day, and 1 MiB HTML. Billing is optional: plan configuration and the admin API let your own service change plans. Never expose the admin secret to clients.

Sign in to Cloudflare and create the storage resources. The names below are examples; any names work when these commands and wrangler.jsonc agree.

npx wrangler login
SELF_HOST_DB=openartifacts
SELF_HOST_BUCKET=openartifacts-docs
npx wrangler d1 create "$SELF_HOST_DB"
npx wrangler r2 bucket create "$SELF_HOST_BUCKET"

The D1 command prints a database_id. Update wrangler.jsonc for your account:

1. Set the Worker name.
2. Set bucket_name to your R2 bucket name.
3. Set database_name and database_id to your D1 values.
4. Replace routes with exactly two custom_domain entries: your document

1. Set SERVING_HOST and API_HOST under vars to those hosts and remove the two legacy host vars. Keep your chosen PLAN_LIMITS/DEFAULT_PLAN.
2. Keep workers_dev set to false.

npx wrangler d1 migrations apply "$SELF_HOST_DB" --remote
SELF_HOST_KEY=$(openssl rand -hex 32)
SELF_HOST_HASH=$(printf '%s' "$SELF_HOST_KEY" | shasum -a 256 | cut -d' ' -f1)
SELF_HOST_NOW_MS=$(($(date +%s) * 1000))
npx wrangler d1 execute "$SELF_HOST_DB" --remote --command \
  "INSERT INTO publishers (key_hash, owner, plan, validated_at)
   VALUES ('$SELF_HOST_HASH', 'self-hosted-owner', 'plus', $SELF_HOST_NOW_MS)"
npx wrangler deploy
OPENARTIFACTS_LICENSE_KEY="$SELF_HOST_KEY" \
  scripts/smoke.sh https://api.example.com

Replace api.example.com with your API host. Save SELF_HOST_KEY in a password manager before closing the terminal. The raw key can publish, list, update, and delete every document owned by self-hosted-owner; only its SHA-256 hash is stored in D1.

Leave LICENSE_API_URL and LICENSE_API_KEY unset for this pre-seeded-key setup. Unknown keys then fail closed. Because workers_dev is disabled, the Worker becomes reachable only after Cloudflare attaches both custom domains.

Optional: private sharing

Documents are all public until you configure reader sign-in, and a server without it answers the private-sharing routes 404, like a server that predates the feature. A plain openartifacts publish publishes nothing there, because the CLI never falls back to a public page after the private route answers 404; pass --public to publish for anyone with the link. To turn it on you need, besides a Google or GitHub OAuth app (or Email Service for emailed codes):

• a READER_SESSION_SECRET Worker secret of at least 32 characters;
• a proxied wildcard DNS record *.{your document host} AAAA to 100:: and

• if you use email, EMAIL_FROM and the send_email binding set for a domain you

Deploying has the whole list and the plan configuration.

Documentation

| Document | Contents | | --- | --- | | HTTP API | Publish, read, list, version, and delete endpoints. | | Hosting | How Workers, R2, and D1 fit together. | | Serving domain | Why uploaded HTML uses a separate registrable domain. | | Identity | Why documents belong to an owner rather than a credential, and how an account is created. | | Private sharing | Invite-only documents: reader sign-in, per-publisher origins, request access, and how access is checked. | | Product analytics | What the five document events carry, and what they deliberately never carry. | | Comments | Inline comments: quote anchors across versions, the per-document Durable Object, access, plans and limits. | | Data model | Every D1 table, R2 key and Durable Object table, and which of them is the system of record. |

Maintainer npm release

Brevilabs maintainers publish the official npm package by merging a vX.Y.Z release PR whose title matches its version bump; the protected workflow is described in the release runbook. This process does not apply to self-hosted deployments.

License

OpenArtifacts is available under the MIT License.