> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-artifacts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run your own instance

> Costs, upgrades, uninstalling and scheduled jobs for a self-hosted Open Artifacts instance.

## Costs

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

### What it uses

| Cloudflare product | Used for |
| - | - |
| Workers | The app, the MCP server, the API, and artifact serving |
| D1 | Metadata and the search index |
| R2 | Artifact files and thumbnails |
| KV | OAuth state for MCP clients |
| Durable Objects | Live-page data, one per artifact |
| Access (Zero Trust) | Login |

### 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](https://developers.cloudflare.com/cloudflare-one/team-and-resources/users/seat-management/) docs and [Zero Trust plans](https://www.cloudflare.com/plans/zero-trust-services/).

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`.

| Limit | Workers Free | Workers Paid |
| - | - | - |
| Live-page data document size | 256 KB | 1 MB |
| MCP request size | 320 KB | 1,088 KB |
| CPU time per request | 10 ms | 30 seconds |

### 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](https://docs.open-artifacts.com/technical-details/self-hosting-set-up.md) 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](https://docs.open-artifacts.com/technical-details/self-hosting-set-up.md).

**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:

```sh theme={null}
if git remote get-url origin | grep -qE '^https?://[^/]*@'; then echo "origin has credentials"; fi
```

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.

```sh theme={null}
git remote set-url origin "$(git remote get-url origin | sed -E 's#^(https?://)[^/]*@#\1#')"
```

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

```sh theme={null}
TAG=$(curl -fsSL https://api.github.com/repos/open-artifacts-ai/open-artifacts/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
git fetch --depth 1 origin tag "$TAG"
git checkout "$TAG"
```

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.

   ```sh theme={null}
   node --experimental-strip-types apps/server/scripts/verify-migration.ts capture --db <db> --out .openartifacts/migration-0017-before.json
   ```

2. **Record a D1 Time Travel bookmark** and keep its `bookmark` value:

   ```sh theme={null}
   pnpm -s --filter @oa/server exec wrangler d1 time-travel info <db> --json
   ```

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.

   ```sh theme={null}
   node --experimental-strip-types apps/server/scripts/verify-migration.ts verify --db <db> --in .openartifacts/migration-0017-before.json
   ```

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.

   ```sh theme={null}
   pnpm -s --filter @oa/server exec wrangler d1 time-travel restore <db> --bookmark=<bookmark>
   ```

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:

```sh theme={null}
pnpm --reporter=silent oa:setup --uninstall --check
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.