Skip to main content
Most people use hosted Open Artifacts instead; this page is for running your own instance. Open Artifacts runs on your own Cloudflare account and domain. The easiest way to install it is to tell your coding agent:
install open-artifacts.com/llms.txt at artifacts.example.com
The agent follows the steps below. The only thing you do yourself is approve the Cloudflare login in your browser.

What you need

  • Node.js 22.13 or later, with pnpm (corepack enable provides it).
  • git.
  • A Cloudflare account. The free plan is enough.
  • A domain on Cloudflare. Open Artifacts uses two hostnames on it: one for the app (for example artifacts.example.com) and one for artifact content (for example artifacts-content.example.com).

Steps

1

Check the prerequisites

Run node --version (needs 22.13 or later), pnpm --version (needs 11.25.0; corepack enable installs it) and git --version. If anything is missing, or the user has no Cloudflare account or no domain on Cloudflare, explain what it is and how to get it, then wait.
2

Clone the latest release

Open Artifacts installs from the latest stable GitHub release, not main and not a pre-release. Release tags look like vX.Y.Z:
Clone outside any existing git repository (the command uses ~/open-artifacts), and tell the user the path: upgrades run from there.If ~/open-artifacts already exists, an install is already there. Go to “Update an existing install” instead of cloning.If TAG comes back empty or curl fails, stop and tell the user: “Open Artifacts has no stable release yet; check back later.”
3

Install dependencies

pnpm install. pnpm may print “Ignored build scripts: esbuild, workerd”. That’s expected, so don’t run pnpm approve-builds.
4

Check the Cloudflare login, then ask the user to log in if needed

First run npx wrangler whoami --json with at least a 3-minute timeout (it can refresh a login). If it lists accounts, skip the login. Otherwise ask them to run npx wrangler login and approve access in the browser. On a remote machine or in a container, use npx wrangler login --device instead. This is the one step a person has to do.
5

Run setup

First ask the user: “Just you, or a team?” Don’t guess. Pass --solo for just them, or --team for a team.
  • Team: in the same message, ask whether the account is on Workers Paid, and pass --yes-paid if so (invite email needs it). Tell them up front that they’ll create a Cloudflare Access token and onboard the sending domain mail.<app-host>. Also tell them that everyone who logs in, viewers included, uses a Cloudflare Zero Trust seat: free up to 50 users, then $7 per user per month for every user (see Self-hosting costs).
  • One hostname: if they gave only one, it’s --app-host. Propose <first-label>-content.<zone> as --content-host (for artifacts.example.com, that’s artifacts-content.example.com) and the email from wrangler whoami as --owner-email, and confirm both.
Then run it with the user’s hostnames and email:
--reporter=silent keeps pnpm’s own output off stdout, so every line is JSON. Do not shorten it to -s: pnpm 11 still prints an [ELIFECYCLE] line on stdout then. With --json, setup never prompts. Setup prints one JSON object per line, {"step", "status", "message", "data"}, where status is ok, skipped, action_required, or error. It stops at the first action_required or error. Then go by the exit code:
  • 0: every step is done. Go on to step 6.
  • 2: the last line is action_required. If its message asks you to pass a flag, such as --account-id when the login can reach several accounts, add that flag and run again; ask the user for the value if you don’t know it. Otherwise relay the message to the user verbatim, with data.url if it has one, wait until they say it’s done, and run the same command again. Setup saves its progress in .openartifacts/state.json and picks up where it stopped.
  • 1: the last line is error. Show the user its message and stop. If the message names DNS, wait 2 minutes and rerun.
If the access step asks for an Access API token, the user creates one at its data.url. Save it with this line in your own terminal (in Claude Code, type ! then the line). Never paste a token into the chat. The line works in bash and zsh. Setup never deletes the file; remove it when you no longer need it. If read fails, the shell can’t hide input, so use a real terminal.
Use your --name in place of open-artifacts in that line. pnpm --reporter=silent oa:setup --token-links --json prints the exact line for every token as saveCommand. Then run the same setup command again. Setup reads the saved file, keeps the token only in memory, and never prints or saves it.The other tokens work the same way, each saved with its own line in your own terminal and never in the chat:
  • Deploy token: ~/.open-artifacts/<name>-cloudflare-token, or --token-file <path>.
  • Access token: ~/.open-artifacts/<name>-access-token, or --access-token-file <path>.
  • Analytics token (optional): ~/.open-artifacts/<name>-analytics-token, or --analytics-token-file <path>.
Once Access is set up, later runs skip re-checking it while the app host and Cloudflare account stay the same. You need the Access token again only to change the app host or account, or to re-check Access.If the prereqs line is action_required with “Pass —solo or —team”, ask the user “Just you, or a team?” and run again with --solo or --team.The Workers plan. The prereqs line has data.plan (free, paid, or unknown) and data.warnings. If it stops because a hostname isn’t in a zone on the account, the line carries only data.missing, with no plan or warnings; once the zone is added and setup runs again, the plan appears. Relay every data.warnings[].message to the user verbatim, and say nothing else about the plan: don’t paraphrase the warnings or add free-plan notes of your own. Relay warnings once; on reruns, relay only new ones.
  • unknown is the common case. wrangler login has no billing access, so setup couldn’t read the plan and relays the Workers Free notes to be safe. The first warning explains this.
  • paid (detected, or confirmed with --yes-paid), with no warnings: tell the user Workers Paid was detected. If they chose --solo, offer the team path: run setup again with --team. Invite emails need an email sending domain (below).
  • A team on a plan that isn’t paid: invite email stays off, except on an unknown plan where an earlier run saved email: true; then it stays on. Otherwise, if the user confirms the account is on Workers Paid, run again with --team --yes-paid.
Invite email (teams only). The email step checks the sending domain, mail.<app-host> unless you pass --email-domain. When it returns action_required, give the user its message, the dashboard link in data.dashboard, and the DNS records in data.records, verbatim. Wait until they’ve onboarded the domain in the dashboard, then run setup again; the records can take 5 to 15 minutes to appear. If the domain already has mail records from another provider, setup asks first: relay that action_required message, and pass --yes-email-domain only if the user agrees. Otherwise pick another --email-domain.
6

Connect yourself

Setup saves your agent token to ~/.open-artifacts/<host-slug>-pat-token (mode 0600), where <host-slug> is the app host lowercased with every run of other characters turned into - (artifacts.example.com becomes artifacts-example-com). The owner-token line’s data.tokenFile is its absolute path. Don’t read or print the file; point your client config at it. Never ask for or paste a token in chat. The agent-config line’s data.url is the MCP URL, and its data.snippets holds a config for claudeCode, cursor, opencode, codex and a generic json. Claude Code, Codex CLI, Cursor and OpenCode log in with OAuth: the snippet is only the MCP URL (claude mcp add --transport http -s user <name> <url>, then /mcp; for Codex, codex mcp login <name>; for OpenCode, opencode mcp auth <name>), with no token or header. Use a token only for a client without OAuth: OpenCode’s opencodeToken snippet reads the file by absolute path ({file:<abs file>}), Codex’s codexToken fallback sets http_headers_helper to read the file (Codex 0.163 or later), and json has a <YOUR_TOKEN> placeholder for the user to fill in themselves, in a file kept out of git. If the file is lost, run setup again with --new-owner-token: it saves a new token to the file first and revokes the old one only after that. If the revoke fails, setup stops with action_required and the file stays; rerun setup to retry it, or revoke the old token in the dashboard (Settings → Connections). Connect agents shows each client’s config format.
7

Open the Welcome page

Setup publishes a Welcome artifact to test the connection. Give the user its link, data.welcomeUrl on the selftest and agent-config lines, so they can log in and see it. A rerun tests with the saved agent token file, so it publishes (updates) the Welcome page too, only when its text changed, and unless that file is missing (a note) or its token is rejected (action_required, data.tokenRejected). When setup finishes, its last line is {"step": "state", "status": "ok", "message": "final"} with data.plan (the plan setup detected), data.planVar (the PLAN var the Worker serves), data.team, data.email, and data.emailDomain. Tell the user whether invite emails are on: with email: true, invites are sent from noreply@<emailDomain>; otherwise they share invite links themselves.

Setup flags

Setup takes each value from its flag first, then from .openartifacts/state.json (saved by an earlier run), then by asking, unless --json or --yes is set. After the first run, the hostnames and email can be left out. Exit codes: 0 when every step is done, 2 when a step needs the user or a missing flag (action_required), and 1 on an error. With --check, 0 means the checks ran; --strict makes a todo step exit 2.

What setup does

oa:setup is idempotent: each step checks first and skips work that’s already done. The steps, in order:
  1. prereqs: checks Node 22.13 or later, pnpm, the Cloudflare login and account, and that both hostnames are in a zone on that account. It reports ok (message “prerequisites ok”); the plan warnings are in data.warnings, other notes in data.notes, and token links in data.tokens. Nothing is added to the message. The optional analytics token link is a note only on the first run.
  2. resources: creates or reuses the D1 database, the R2 bucket, and the KV namespace, and writes apps/server/wrangler.jsonc.
  3. access: creates the Cloudflare Access for SaaS application and its login policy.
  4. secrets: stores the Worker secrets. When ANALYTICS_TOKEN is set in the environment (a dedicated read-only token with Account Analytics: Read, never your deploy token), it stores it on every run. Otherwise, without --json or --yes, it offers to store one for the Usage page, with a link that pre-fills the token form.
  5. deploy: builds the server, applies database migrations, and deploys the Worker. If the live version is the one setup last deployed and a dry-run build of the Worker (its .js and .wasm output, built twice to check it is deterministic) plus the rendered config, wrangler version and repo version hash the same as last time (state.deployHash), it skips wrangler deploy and the line is skipped (“already deployed <version>”); migrations still run. An unknown hash (a failed dry run, a non-deterministic build) never skips, and a rollback clears the hash.
  6. healthcheck: before any token is minted, checks /healthz (and that its plan matches the PLAN var setup rendered), the OIDC discovery document and, for email, the EMAIL binding. It retries for about a minute while certificates and the deploy propagate, and for up to 5 minutes while the app or content host doesn’t resolve. After about a minute it asks public DNS (over DoH; A, AAAA and CNAME all count): a live record means your machine’s DNS cache has a stale miss (action_required, with the flush command for your OS); if the record isn’t live it keeps waiting, then fails naming the missing record. If DoH can’t answer, it says so and to wait 2 minutes and rerun. Under --ci there is no extra wait and no DoH: about a minute, then an error with the cause code.
  7. owner-token: mints a personal access token for the owner, unless setup already minted one that’s still valid, and saves it to ~/.open-artifacts/<host-slug>-pat-token (mode 0600) without printing it.
  8. selftest: publishes the Welcome artifact over MCP with this run’s token (or, on a rerun, the saved token file) and checks that its content is served. The page is published only when its text changed since the last publish. A missing file is a note, not a failure; a saved token the server rejects (401 or 403) is action_required (exit 2) with data.tokenRejected: true: rerun with --new-owner-token and update the client.
  9. agent-config: prints the MCP URL and config snippets. It always runs, even when healthcheck or selftest fails (then with the OAuth snippets only; the token-file fallbacks appear once the token exists).

Plan warnings

The prereqs line’s data.warnings holds one { code, plan, message } per note below, and agents relay each message verbatim. With data.plan unknown, setup sends the first five; with free, the same minus plan-unknown. browser-free appears only with --browser on a plan that isn’t paid. Once Paid is confirmed (--yes-paid, --plan paid, or a saved plan), none of these warnings are sent, and the prereqs message says how it was confirmed. On Workers Paid (data.plan paid), data.warnings is empty and the prereqs line says so in data.notes (“Workers Paid detected”). When prereqs stops because a hostname isn’t in a zone, its action_required line carries only data.missing: no plan, no warnings, and no “Workers Paid detected”.

Cloudflare Access permissions

The token from wrangler login may not be able to manage Zero Trust (Access). If it can’t, the access step asks for an API token with Access: Apps and Policies Edit and Access: Organizations Read, and links to a pre-filled form for creating one. Save it with the line from --token-links (setup reads ~/.open-artifacts/<name>-access-token); in an interactive run, you can paste it at the prompt instead. Setup doesn’t keep it. Later runs skip re-checking Access without it, unless the app host or account changes. If the account has no Zero Trust organization yet, setup links to the Zero Trust dashboard to turn it on. Zero Trust’s free plan is enough.