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.
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.
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 variablePLAN 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.
--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 If
vX.Y.Z: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_requiredline’smessageto the user verbatim, wait until they’ve done it, then run the same command again. - 1: show the user the
errorline’smessage. If it says to rerun setup without--upgrade, runpnpm --reporter=silent oa:setup --json, then the upgrade again. That run may need the Access token again. Get its save line frompnpm --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. Ifreadfails, 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)
Migration0017_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:
-
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.
-
Record a D1 Time Travel bookmark and keep its
bookmarkvalue: - Upgrade (step 6 of the upgrade steps).
-
Verify. Exit 0 means every row, index, trigger and the search index are as before,
foreign_key_checkis empty and the integrity check passes. -
If verify fails, restore the database, then roll the Worker back as your instance’s
/upgrade.mddescribes (its step 8). A restore discards every write since the bookmark: anything published, shared or written to live data during the upgrade is lost.
If the Cloudflare login has expired
Theprereqs 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:--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, fromapps/server’s wrangler (pnpm --dir apps/server exec wrangler ...):
- Database: a whole-database
wrangler d1 exportfails 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: itsINSERTcount must equalwrangler 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) andd1_migrations. An export locks the database while it runs. - Files in R2:
rclone sync r2:<name> ./backup-r2copies the whole bucket. It needs R2 S3 credentials (dashboard, R2, Manage API Tokens). To fetch single keys, list them in the dashboard or withrclone lsf r2:<name>, thenwrangler 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.
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).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_ranwith thedayandvia(slotfor the tick,dailyfor 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 the17 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.