Run it

Self-hosting

Run your own artifacts.space on Vercel with Neon Postgres, Better Auth, GitHub and Google sign-in, Cloudflare R2, and Sendir.

What you needLink to this section

artifacts.space is one Next.js app. To run your own you need:

  • Postgres. Neon in production; any Postgres on localhost for development.
  • A host for Next.js 16. The repository is set up for Vercel, including its crons.
  • Sendir for email: sign-in links, invitations, mentions, and reports. People sign in with email links, so production needs it.
  • Cloudflare R2 for uploaded files. Without it, everything but files works.
  • A GitHub OAuth app, if you want GitHub sign-in. Optional.
  • A Google OAuth client, if you want Google sign-in. Optional.
  • A second domain, if you want web pages (html artifacts) to run. Optional: set it as PAGE_HOST. Without it, such an artifact shows its source and does not run.
  • Node.js 22.22.1 or later and pnpm 10. CI and production run Node 26, the version in .nvmrc.

The source is at github.com/artifacts-space/artifacts-space.

Environment variablesLink to this section

Put these in .env.local for development, and in your host's settings for production. .env.example lists the same set.

VariableNeededWhat it does
DATABASE_URLrequiredPostgres connection string. Neon's pooled URL in production; a localhost URL uses a plain pg pool.
DATABASE_URL_UNPOOLEDoptionalDirect (unpooled) connection for migrations. Vercel production builds need it to apply migrations; pnpm db:migrate falls back to DATABASE_URL. In .env.local it comes first for migrations, so fill it in or leave it out (it is commented out in .env.example). A value set for the command wins over .env.local, and DATABASE_URL set alone serves for both.
E2E_LOCAL_DBoptionalDevelopment only. Set to 1, with DATABASE_URL on localhost, to run the end-to-end checks that seed a throwaway database. Otherwise the end-to-end dev server gets no database at all.
ALLOW_SHARED_MIGRATEoptionalSet to 1 for one run to let pnpm db:migrate (or drizzle-kit push) change a database that is not on localhost, such as yours when you migrate by hand. Without it, they stop before they connect. Vercel production builds migrate on their own and never need it.
BETTER_AUTH_SECRETrequiredSigns sessions. At least 32 characters: openssl rand -base64 32.
BETTER_AUTH_URLrequiredThis site's origin, such as https://artifacts.example.com. Every absolute link, the OAuth issuer, and the MCP resource come from it.
GITHUB_CLIENT_IDoptionalGitHub OAuth app. Without both GitHub values, GitHub sign-in is off and email links remain.
GITHUB_CLIENT_SECREToptionalSecret for the GitHub OAuth app.
GOOGLE_CLIENT_IDoptionalGoogle OAuth client (Web application) with the redirect URI <BETTER_AUTH_URL>/api/auth/callback/google. Without both Google values, or with a replace-with-… placeholder, Google sign-in is off and its button is hidden. The sign-in pages read them when the app builds, so a change needs a new build, not just a restart.
GOOGLE_CLIENT_SECREToptionalSecret for the Google OAuth client.
SENDIR_API_KEYfor emailSendir key scoped to the sending identity. Production cannot send sign-in links without it.
SENDIR_IDENTITY_IDfor emailThe Sendir identity whose address sends every email.
SENDIR_URLoptionalOverrides https://sendir.ai.
ABUSE_REPORT_EMAILfor emailThe site operator's address. Every reader report on an artifact is emailed here, and only here. Without it, reports are still stored and shown on the team page, and each one logs a warning.
SLACK_FEEDBACK_WEBHOOK_URLoptionalSlack Incoming Webhook for "Something's not working" reports from the account menu. Must start with https://hooks.slack.com/. Keep it secret. Without a valid one, the dialog says feedback is not available.
OPENAI_APPS_CHALLENGE_TOKENoptionalThe domain verification token OpenAI's plugin submission portal shows. Served as plain text at /.well-known/openai-apps-challenge; without it that path returns 404. Not a secret, but set it only on the deployment you submit.
R2_ACCOUNT_IDfor filesCloudflare account id for R2.
R2_BUCKETfor filesThe bucket that holds uploads.
R2_ACCESS_KEY_IDfor filesS3 access key: the id of an API token scoped to the bucket.
R2_SECRET_ACCESS_KEYfor filesS3 secret: the SHA-256 of that token.
R2_ENDPOINToptionalAnother S3-compatible endpoint, such as http://localhost:9000 for a local store in end-to-end tests. https, or http on localhost only. Leave it unset in production.
CRON_SECRETrequiredAt least 16 characters. Vercel Cron sends it as a bearer token to /api/cron/*.
VAPID_PUBLIC_KEYoptionalBrowser notifications (Web Push). Generate a pair with node scripts/generate-vapid-keys.mts. Without all three VAPID values, the browser option is hidden and in-app notifications still work.
VAPID_PRIVATE_KEYoptionalThe private half of the VAPID pair. Keep it secret; changing it ends every browser's subscription.
VAPID_SUBJECToptionalA contact for push services: mailto:you@example.com or an https:// URL.
STORAGE_QUOTA_CONTENT_BYTESoptionalArtifact content quota per account, in bytes. Default 100 MB.
STORAGE_QUOTA_FILE_BYTESoptionalFile quota per account, in bytes. Default 1 GB.
PAGE_HOSToptionalA second domain where pages with scripts run, such as pages.example.net: a different site from BETTER_AUTH_URL, never a subdomain of it. Point a wildcard (*.pages.example.net) at this app, with a certificate for it. Each artifact's page then runs on its own subdomain, apart from every session and every other artifact. That domain serves one frame document and nothing else: every other host under it answers 404. Set it for the build as well as at run time, and never point the domain itself (without a subdomain) at this app. Without it, such pages do not run. Under next dev it defaults to localhost.
FRAME_CAPTURESoptionalSet to off to stop storing images of canvas frames, which the browsers of people who may edit a canvas draw so agents can see it. On by default where file storage is set up.
VERCEL_PROJECT_PRODUCTION_URLplatformSet by Vercel. The site origin when BETTER_AUTH_URL is unset.
VERCEL_ENVplatformSet by Vercel. Production and preview share one email budget; anything else counts its own. Problem reports name it with the commit. Google sign-in is off on preview, whose URLs are not registered with Google, and so are images of canvas frames.
VERCEL_GIT_COMMIT_SHAplatformSet by Vercel. Problem reports name the deploy by its short commit.
NODE_ENVplatformSet by Next.js. Development turns on the dev sign-in route and prints sign-in links instead of sending them.

Keep secrets out of the repository

.env.local is ignored by Git. Never commit keys, and give each environment its own BETTER_AUTH_SECRET.

Database and migrationsLink to this section

The schema lives in src/db/schema.ts, src/db/oauth-schema.ts, src/db/views-schema.ts, and src/db/notification-schema.ts; migrations are SQL files in drizzle/, managed by drizzle-kit. On Vercel, every production build applies pending migrations before the new code goes live (see Deploy on Vercel). Anywhere else, apply them before the first start and after every update:

pnpm db:migrate

Migrations use DATABASE_URL_UNPOOLED (the direct connection) when it is set, and DATABASE_URL otherwise; the app uses DATABASE_URL. In .env.local, fill in both or leave DATABASE_URL_UNPOOLED out, as .env.example does. On Neon, the Vercel integration sets both. drizzle-kit reads .env.local itself, and a URL you set for the command wins over it (DATABASE_URL alone serves for both). pnpm db:migrate changes only a database on localhost unless you set ALLOW_SHARED_MIGRATE=1 for that run, so a test run never migrates your production database by mistake. Only the public schema is managed.

The old code keeps serving while a deploy migrates, so migrations stay additive: add columns and tables, backfill, then switch the code. pnpm check rejects drops, renames, type changes, and new required columns without a default.

Sign-inLink to this section

Sign-in is Better Auth, self-hosted: email links and, optionally, GitHub and Google. Nobody can sign up with a password or set one on the web: a password signs in only to an account you gave one with pnpm reviewer:create (scripts/create-reviewer-account.mts), such as a test login for a directory review. Better Auth is also the OAuth 2.1 server MCP clients connect through, at <BETTER_AUTH_URL>/api/auth.

  • Set BETTER_AUTH_URL to the public origin. OAuth tokens are bound to <BETTER_AUTH_URL>/api/mcp, so a wrong origin breaks MCP sign-in.
  • For GitHub, create an OAuth app with the callback URL <BETTER_AUTH_URL>/api/auth/callback/github. The GitHub login becomes the preferred username.
  • For Google, create an OAuth client of type Web application with the authorized redirect URI <BETTER_AUTH_URL>/api/auth/callback/google, and ask only for the openid, email, and profile scopes. The button shows only when both Google values are set, and never on Vercel preview deploys, because Google accepts only exact redirect URIs. The sign-in pages read the Google values when the app builds, so after you change them, build again; a restart is not enough.
  • A GitHub or Google sign-in whose email matches an existing account joins that account only when the provider has verified the email and the account has confirmed it. Google may create or join an account only for an address it hosts: Gmail, or a Google Workspace domain. A Google account on any other address, or with an unverified one, is sent back to use an email link. Google's tokens are not kept.
  • MCP apps register themselves. Apps nobody approves are deleted after 24 hours. One network address may have 100 of them waiting, and at most 2000 wait at once. Past either cap, a new registration removes the oldest one that has waited over 15 minutes, from the same address first, and registration pauses only while all of them are newer.

File storage on R2Link to this section

Browsers upload straight to R2 with presigned URLs, and downloads go through an access-checked redirect. Set up:

  1. Create a bucket.
  2. Create an R2 API token scoped to that bucket. The S3 access key id is the token id; the secret is the SHA-256 of the token value.
  3. Add a CORS rule for your origin, because the browser PUTs to the bucket directly:
R2 CORS policyjson
[
  {
    "AllowedOrigins": [
      "https://artifacts.example.com"
    ],
    "AllowedMethods": [
      "PUT",
      "GET",
      "HEAD"
    ],
    "AllowedHeaders": [
      "content-type"
    ],
    "MaxAgeSeconds": 3600
  }
]

Files are capped at 25 MB. If the R2 variables are missing, file requests fail with a message that names them; everything else keeps working.

Email with SendirLink to this section

Every email goes out through Sendir from one identity. Set SENDIR_API_KEY (scoped to that identity) and SENDIR_IDENTITY_ID. In production, sign-in fails without them. In development without them, sign-in links print to the dev server log.

Invitations, mentions, and report emails share a daily budget below the provider's cap, so sign-in links always get through. If your Sendir cap differs, change SENDIR_DAILY_RECIPIENTS in src/lib/email/budget-rules.ts. See Email budget.

Deploy on VercelLink to this section

  1. Import the repository into Vercel. It detects Next.js and pnpm.
  2. Add Neon from the Vercel Marketplace, which sets the database variables, and add the rest from the table above.
  3. Deploy. The production build runs scripts/migrate-on-deploy.mts first: it applies pending migrations over DATABASE_URL_UNPOOLED, one build at a time. If a migration fails, the build fails and the previous deployment keeps serving. Preview and local builds skip this step, so an unmerged migration never reaches your database.
  4. Point your domain at the project and set BETTER_AUTH_URL to it.

vercel.json schedules two cleanup jobs. Vercel sends CRON_SECRET as a bearer token; requests without it are refused.

PathSchedule (UTC)
/api/cron/cleanup-files23 */6 * * *
/api/cron/cleanup-oauth24 */6 * * *

cleanup-files deletes unfinished and unattached uploads and prunes versions past 100 or 365 days. cleanup-oauth deletes unapproved MCP apps, expired access tokens, and old refresh tokens, and forgets which address registered each app after 18 hours. On another host, call both paths on the same schedule with Authorization: Bearer $CRON_SECRET.

Run it locallyLink to this section

Terminalbash
git clone https://github.com/artifacts-space/artifacts-space.git
cd artifacts-space
pnpm install
cp .env.example .env.local     # fill in DATABASE_URL, BETTER_AUTH_SECRET, CRON_SECRET
pnpm db:migrate                # a database not on localhost: ALLOW_SHARED_MIGRATE=1 pnpm db:migrate
pnpm dev

The app runs on http://localhost:3000. Without Sendir keys, open /api/dev/sign-in to sign in as a development user in one step; it exists only under next dev and is off while Sendir keys are set. Before you push, run pnpm check (typecheck, lint, file length, tests) and pnpm build.