Skip to main content

Costs

Every feature works on the Cloudflare Workers Free plan. For personal use, an instance usually costs nothing.

What it uses

Access login seats

Every person who logs in to your instance through Cloudflare Access, viewers included, uses a Zero Trust seat. A seat is held until you remove the user, however many times they log in.
  • Free plan: up to 50 users at no cost. Once all 50 seats are used, new users can’t log in.
  • Pay-as-you-go: $7 per user per month, and every user is billable, not just those past 50.
To see or free seats, open Zero Trust → Team & Resources → Users in the Cloudflare dashboard. You can also turn on seat expiration there, so people who haven’t logged in for a while stop using a seat. Sources: Cloudflare’s seat management docs and Zero Trust plans. A personal instance uses one seat. For a team, count everyone you’ll share with. A login option that doesn’t use Access is planned.

Staying within the free plan

The free plan allows 100,000 Worker requests a day and 10 ms of CPU time per request. Open Artifacts is built to those limits:
  • Markdown, code highlighting, PDFs, and diffs render in the viewer’s browser, not the Worker.
  • Large uploads stream straight to R2 instead of passing through the Worker.
  • Every request path is tested against the CPU budget.
The dashboard’s Usage page shows today’s requests, database reads and writes, and KV writes, plus a CPU card with how many requests hit the CPU limit and how much CPU a typical busy request uses. It warns as you near the limits. It needs an optional ANALYTICS_TOKEN secret with Account Analytics read access; without it, the page explains how to add one.

Free vs Paid limits

An instance applies the Workers Free limits unless its Worker variable PLAN is paid. Setup sets PLAN from your Cloudflare plan: paid when it reads Workers Paid or you pass --yes-paid, otherwise free. Pass --plan paid or --plan free to choose it yourself. /healthz reports the value as plan.

Hitting the CPU limit

On the Workers Free plan, each request gets 10 ms of CPU time. A request that needs more is stopped by Cloudflare. You might notice:
  • A publish or a page load that fails, sometimes with Cloudflare’s Error 1102 (“Worker exceeded resource limits”).
  • An agent reporting a failed publish that works when it tries again.
  • A note at the end of an agent’s tool result saying your instance hit the free-plan CPU limit several times today. It appears once there are 3 or more hits in a day.
  • A notice in the dashboard saying your instance hit the CPU limit today.
It usually comes from bursts of large publishes. A few hits a day are normal, and a retry generally succeeds. To see how often it happens, open Settings → Usage in the dashboard. The CPU card shows how many requests hit the limit today and how much CPU a typical busy request uses compared with the 10 ms budget. If it happens often, move the account to Workers Paid ($5 a month), which raises the limit to 30 seconds per request. In the Cloudflare dashboard, go to Workers & Pages → Plans and choose Paid. The CPU limit rises right away. To also get the Paid size limits above, run setup again with --upgrade --plan paid.

When to upgrade

The free plan handles personal use; sustained bursts of large publishes can exceed the 10 ms CPU limit. Workers Paid ($5 a month) is recommended for heavy or team use. Consider Workers Paid (from $5 a month) if you publish heavily, share public links that get a lot of traffic, or run busy live pages. Paid plans raise the request and CPU limits. After upgrading, run setup again with --upgrade --plan paid so the instance uses the Paid limits too. Server-side thumbnails (Browser Run) are best-effort and work best on Workers Paid. On Free, previews fall back to the in-browser capture. Cloudflare’s free allowances change from time to time. Check Cloudflare’s pricing pages for the current numbers.

Upgrade

Upgrades keep all your artifacts, versions, shares, and live-page data. Database migrations add to the schema; they never rename or drop anything your data depends on. One migration, 0017_image_format, rebuilds three tables to allow image artifacts; it runs guarded (see below).

Steps

1

Go to the existing install

cd into the directory setup cloned into (by default ~/open-artifacts). If it’s gone, for example on a new machine or in CI, clone the latest release as in setup and continue from step 4. Without its saved state, add the install’s --name (and --account-id if the login has several accounts); setup reads the hosts and owner email from the deployed Worker. It also re-verifies Access, so you may need the Access token again if the Cloudflare login can’t read Access; save it as in setup.
2

Check the git remote for credentials

Never print the remote URL or the git settings: a token in the URL would be exposed. This prints a line only if the URL has a login in it:
If it prints that line, take the login out of the URL before you go on. The repository is public, so fetching needs no login. Then revoke that token where you made it, since it was stored in plain text.
To show the remote without the login: git remote get-url origin | sed -E 's#^(https?://)[^/]*@#\1***@#'.
3

Check out the latest release

This is the latest stable GitHub release; pre-releases are skipped. Release tags look like vX.Y.Z:
If TAG comes back empty or curl fails, stop and tell the user: “Open Artifacts has no stable release yet; check back later.”An instance below 0.109.0 upgrades to v0.109.0 first, then to the latest: from 0.109.0 the agent bus’s storage ships one release before the code that turns it on. Setup stops with action_required and says so.
4

Install dependencies

pnpm install --frozen-lockfile.
5

Preview, if you like

pnpm --reporter=silent oa:setup --upgrade --check --json is read-only. It reports each step as done or todo without changing anything, so you can see what the upgrade would do. Steps that always run show todo; that isn’t pending work.
6

Run the upgrade

pnpm --reporter=silent oa:setup --upgrade --json. It uses your wrangler login. In CI, or on a machine with no login, use a Cloudflare deploy token instead, as your instance’s /upgrade.md does. pnpm --reporter=silent oa:setup --token-links --json prints the link that creates it (with the permissions it needs) and the line that saves it as ~/.open-artifacts/<name>-cloudflare-token. Run that line in your own terminal, then put CLOUDFLARE_API_TOKEN="$(cat ~/.open-artifacts/<name>-cloudflare-token)" in front of the command. It reuses the hostnames and email saved by setup. Every step runs, but only deploy (new database migrations, then a redeploy), healthcheck, selftest and agent-config do work: prereqs reports ok (its data.warnings and data.notes hold plan warnings and notes) and resources verifies, and access, secrets and owner-token report skipped unless something is missing. It keeps the existing owner token and needs no OA_ACCESS_TOKEN when the state is saved. It never creates resources: if one is missing, it reports action_required and asks for a full setup. Go by the exit code, as in setup:
  • 0: done.
  • 2: relay the action_required line’s message to the user verbatim, wait until they’ve done it, then run the same command again.
  • 1: show the user the error line’s message. If it says to rerun setup without --upgrade, run pnpm --reporter=silent oa:setup --json, then the upgrade again. That run may need the Access token again. Get its save line from pnpm --reporter=silent oa:setup --token-links --json (saveCommand) and have the user run it in their own terminal (in Claude Code, type ! then the line). Never paste a token into the chat. If read fails, the shell can’t hide input, so use a real terminal. Setup then reads ~/.open-artifacts/<name>-access-token.
7

Tell the user

which version is now running: the deploy line’s data.deployedVersion.

The guarded migration (0017, image format)

Migration 0017_image_format rebuilds the artifacts, versions and shares tables to widen their format check to image, keeping every row and rowid, index, trigger and the search index. Because it isn’t purely additive, record a way back and check the result. From the release directory, with the deploy token in CLOUDFLARE_API_TOKEN (and CLOUDFLARE_ACCOUNT_ID if the token reaches several accounts), and <db> your install name:
  1. Capture the database before the upgrade. Exit 1 with “already applied” means the instance already has it: upgrade as usual. Any other exit 1, or exit 2: stop, and don’t upgrade; the message says why.
  2. Record a D1 Time Travel bookmark and keep its bookmark value:
  3. Upgrade (step 6 of the upgrade steps).
  4. Verify. Exit 0 means every row, index, trigger and the search index are as before, foreign_key_check is empty and the integrity check passes.
  5. If verify fails, restore the database, then roll the Worker back as your instance’s /upgrade.md describes (its step 8). A restore discards every write since the bookmark: anything published, shared or written to live data during the upgrade is lost.
Verify reports rows added while the upgrade ran as notes, never as failures, and so are rows the app deleted meanwhile when their audit row or state explains them (an unshare, a transfer, a directory removal, an address change, the trash purge). A captured row that’s gone otherwise, a change to the three rebuilt tables other than the widened check, a search row detached from its artifact, a foreign key violation or a failed integrity check fails it. Later migrations may add or change other objects.

If the Cloudflare login has expired

The prereqs step fails with an error. Ask the user to run npx wrangler login again, then re-run the upgrade.

Uninstall

Setup has no delete command yet. To see exactly what your instance has, run the dry run from the directory setup cloned into. It reads only the saved state and changes nothing:
Add --json for a machine-readable list. With no saved state, pass --name; it lists the resources by name (<name>, <name>-oauth), and the KV step shows how to find its id. A --name that differs from the saved one is refused. Then remove the pieces in this order, so nothing points at something already gone.

Before you start: back up

Deleting the D1 database and the R2 bucket destroys every artifact, version, share, and live-page data value. It cannot be undone. Back up first, from apps/server’s wrangler (pnpm --dir apps/server exec wrangler ...):
  • Database: a whole-database wrangler d1 export fails here, because the search index is a virtual table. Export the tables instead. List them at run time: wrangler d1 execute <name> --remote --json --command "SELECT name FROM sqlite_master WHERE type='table' AND name NOT GLOB 'artifact_search*' AND name NOT GLOB 'sqlite_*' AND name NOT GLOB '_cf_*' AND name != 'd1_migrations'". Then run one export per table <t> it returned: wrangler d1 export <name> --remote --no-schema --table <t> --output <t>.sql. Check each file: its INSERT count must equal wrangler d1 execute <name> --remote --command "SELECT COUNT(*) FROM <t>". Empty tables are normal. Skipped on purpose: the search index (artifact_search*, a virtual table), Cloudflare’s internal _cf_* tables, sqlite_* tables (sqlite_sequence) and d1_migrations. An export locks the database while it runs.
  • Files in R2: rclone sync r2:<name> ./backup-r2 copies the whole bucket. It needs R2 S3 credentials (dashboard, R2, Manage API Tokens). To fetch single keys, list them in the dashboard or with rclone lsf r2:<name>, then wrangler r2 object get <name>/<key> --remote --file <path>. Without --remote, wrangler reads a local store, not your bucket.
  • Not exported: live-page and agent bus state lives in Durable Objects, which deleting the Worker destroys. No export covers it.
  • Lighter option: ask any AI agent: “Save the latest version of every artifact I own into a folder on this computer.” This saves only the latest versions, not history, shares or data.
If an export fails, or a count does not match, stop and don’t delete anything. Restore is not supported yet. This copy is for safekeeping.

Order

1

The Access app

(and any orphaned one: state.json pendingAccessAppId is an app a stopped setup run left behind). Zero Trust dashboard, Access, Applications, the app named like your install, Delete. Its policy, “Open Artifacts – everyone”, can go too if nothing else uses it. Do this first so no login page is left guarding a host with nothing behind it.
2

The email domain, if you turned on email

Dashboard, Email Service, Email Sending, remove the sending domain (<domain> is mail.<app host> unless you passed --email-domain). Then in the zone’s DNS page delete what onboarding added: MX cf-bounce.<domain>, TXT cf-bounce.<domain> (SPF), and TXT cf-bounce._domainkey.<domain> (DKIM). Delete TXT _dmarc.<domain> only if onboarding created it; on an apex sending domain it may be your own policy.
3

The custom domains

The app host and the content host are attached to the Worker. Deleting the Worker releases them. To free them first: Workers & Pages, the Worker, Settings, Domains & Routes, delete each.
4

The Worker

pnpm --dir apps/server exec wrangler delete --name <name>. This destroys its Durable Objects (ArtifactRuntime, BusHub, DirectorySync, UserPresence), which hold live-page and agent bus state. That state is not exported and is lost.
5

The KV namespace

(<name>-oauth). pnpm --dir apps/server exec wrangler kv namespace delete --namespace-id <id>.
6

The D1 database

(<name>). pnpm --dir apps/server exec wrangler d1 delete <name>. This destroys data. Cloudflare can undelete a D1 database only within 7 days.
7

The R2 bucket

(<name>). Empty it first. The dashboard’s select all clears only the listed page, so for a bulk path add a lifecycle rule that expires all objects (R2, the bucket, Settings, Object lifecycle rules) and wait for it to run, or run rclone purge r2:<name>. Then pnpm --dir apps/server exec wrangler r2 bucket delete <name>. This destroys data.
8

Local files, last

Delete .openartifacts/state.json and the rendered apps/server/wrangler.jsonc in the clone and ~/.open-artifacts/<name>-*-token (plus <host>-pat-token). Revoke the Cloudflare API tokens you made for setup in the dashboard (My Profile, API Tokens).
The dry run prints the ids and names for your instance, so you can paste the commands as they are.

Scheduled jobs

A self-hosted install has one cron trigger, */2 * * * * (every 2 minutes). Workers Free allows 5 cron triggers per account, so one per install leaves room for others. Code: apps/server/src/cron.ts.
  • Every tick re-queues search indexing and thumbnail jobs a publish lost: a couple of indexed reads when there is nothing to do.
  • The daily work (trash purge, upload and login code sweeps, the release check, audit retention, the directory sync kick) runs on the first tick from 03:17 up to 03:30 UTC that claims the UTC day, so a missed tick doesn’t skip a day. Each run logs cron_daily_ran with the day and via (slot for the tick, daily for the older trigger).
  • The older daily trigger, 17 3 * * *, still works: an install that has it, alone or with the 2-minute trigger, runs the daily work once a day. Both triggers claim the same day, so the order they fire in doesn’t matter.

Rolling back below this release

Releases before the one-trigger cron treat every non-system cron as the daily one. On the 2-minute trigger they would run the daily work every 2 minutes, including a GitHub release check 720 times a day. A rollback to an older release must restore the 17 3 * * * trigger (and drop */2 * * * *). Setup does this for you when it deploys the older release. If you roll back another way (redeploying an old build, or the Cloudflare dashboard’s rollback, which keeps the current triggers), set the trigger yourself under the Worker’s Settings → Trigger events in the Cloudflare dashboard.