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 (
htmlartifacts) to run. Optional: set it asPAGE_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.
| Variable | Needed | What it does |
|---|---|---|
| DATABASE_URL | required | Postgres connection string. Neon's pooled URL in production; a localhost URL uses a plain pg pool. |
| DATABASE_URL_UNPOOLED | optional | Direct (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_DB | optional | Development 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_MIGRATE | optional | Set 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_SECRET | required | Signs sessions. At least 32 characters: openssl rand -base64 32. |
| BETTER_AUTH_URL | required | This site's origin, such as https://artifacts.example.com. Every absolute link, the OAuth issuer, and the MCP resource come from it. |
| GITHUB_CLIENT_ID | optional | GitHub OAuth app. Without both GitHub values, GitHub sign-in is off and email links remain. |
| GITHUB_CLIENT_SECRET | optional | Secret for the GitHub OAuth app. |
| GOOGLE_CLIENT_ID | optional | Google 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_SECRET | optional | Secret for the Google OAuth client. |
| SENDIR_API_KEY | for email | Sendir key scoped to the sending identity. Production cannot send sign-in links without it. |
| SENDIR_IDENTITY_ID | for email | The Sendir identity whose address sends every email. |
| SENDIR_URL | optional | Overrides https://sendir.ai. |
| ABUSE_REPORT_EMAIL | for email | The 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_URL | optional | Slack 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_TOKEN | optional | The 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_ID | for files | Cloudflare account id for R2. |
| R2_BUCKET | for files | The bucket that holds uploads. |
| R2_ACCESS_KEY_ID | for files | S3 access key: the id of an API token scoped to the bucket. |
| R2_SECRET_ACCESS_KEY | for files | S3 secret: the SHA-256 of that token. |
| R2_ENDPOINT | optional | Another 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_SECRET | required | At least 16 characters. Vercel Cron sends it as a bearer token to /api/cron/*. |
| VAPID_PUBLIC_KEY | optional | Browser 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_KEY | optional | The private half of the VAPID pair. Keep it secret; changing it ends every browser's subscription. |
| VAPID_SUBJECT | optional | A contact for push services: mailto:you@example.com or an https:// URL. |
| STORAGE_QUOTA_CONTENT_BYTES | optional | Artifact content quota per account, in bytes. Default 100 MB. |
| STORAGE_QUOTA_FILE_BYTES | optional | File quota per account, in bytes. Default 1 GB. |
| PAGE_HOST | optional | A 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_CAPTURES | optional | Set 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_URL | platform | Set by Vercel. The site origin when BETTER_AUTH_URL is unset. |
| VERCEL_ENV | platform | Set 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_SHA | platform | Set by Vercel. Problem reports name the deploy by its short commit. |
| NODE_ENV | platform | Set 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:migrateMigrations 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_URLto 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 theopenid,email, andprofilescopes. 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:
- Create a bucket.
- 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.
- Add a CORS rule for your origin, because the browser PUTs to the bucket directly:
[
{
"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
- Import the repository into Vercel. It detects Next.js and pnpm.
- Add Neon from the Vercel Marketplace, which sets the database variables, and add the rest from the table above.
- Deploy. The production build runs
scripts/migrate-on-deploy.mtsfirst: it applies pending migrations overDATABASE_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. - Point your domain at the project and set
BETTER_AUTH_URLto it.
vercel.json schedules two cleanup jobs. Vercel sends CRON_SECRET as a bearer token; requests without it are refused.
| Path | Schedule (UTC) |
|---|---|
| /api/cron/cleanup-files | 23 */6 * * * |
| /api/cron/cleanup-oauth | 24 */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
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 devThe 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.