Skip to content

Self-Hosting

Purple Cat's source is public and you can run your own instance.

Licence

Purple Cat is released under the Prosperity Public License 3.0.0.

In plain terms:

  • ✅ Run it for yourself and your group, free.
  • ✅ Modify it, share your modifications.
  • ✅ Use it for your own games, including games you stream or get paid to run.
  • ❌ Run it as a commercial service for other people.
  • ❌ Sell it, or monetise the software itself.

Commercial and hosting rights are reserved by Purple Cat Games, LLC. If you want to do something the licence does not permit, ask.

The full text ships with the source as LICENSE.md.

What "self-hosted" means for you

You are the operator. That means:

  • Your data is yours, on your infrastructure.
  • You get no support and no warranty from Purple Cat Games.
  • The hosted service's Terms and Privacy Policy do not apply to your instance. If other people use it, you are responsible for their data and for giving them your own privacy notice.
  • Updates are your job. Watch releases; some carry database migrations.

Requirements

Requirement Notes
Node.js 26+ Enforced by the repo
pnpm 9+ The workspace's package manager
A database SQLite for local play; PostgreSQL for anything shared
Object storage Optional — local filesystem storage works out of the box; S3 or Google Cloud Storage for a real deployment
A Clerk account Sign-in is handled by Clerk, including for self-hosted instances

Quickest start

npm create purple-cat@latest

The bootstrapper clones the repository, installs dependencies, and runs a guided setup that writes your configuration files and asks which modules you want.

If you already have a clone:

pnpm run setup

Use pnpm run setup, not bare pnpm setup — the latter is a built-in pnpm command and will not run this repository's script.

Then:

pnpm install
pnpm dev
  • App: http://localhost:5173
  • API health check: http://localhost:3001/health

Configuration

Configuration is environment variables in a .env file at the repository root. The setup assistant writes most of them. The ones that matter most:

Variable Purpose
VITE_CLERK_PUBLISHABLE_KEY Clerk, browser side — required, the build fails without it
CLERK_SECRET_KEY Clerk, server side
POSTGRES_URL / DATABASE_URL PostgreSQL. Without either, SQLite is used
STORAGE_S3_BUCKET Use S3 for uploads
STORAGE_GCS_BUCKET Use Google Cloud Storage for uploads
SMTP_HOST, SMTP_USERNAME, SMTP_PASSWORD Email, optional — invite links work without it
OPENAI_API_KEY, GEMINI_API_KEY, CLAUDE_API_KEY, GROK_API_KEY Server-side AI providers, all optional
REPLICATE_API_TOKEN Funds the object-extraction sweep for users who have not entered their own token in Settings. Optional; ~$0.02 an image on Replicate — set a spend cap there first
SAM2_SERVICE_URL Your own SAM 2 service instead of Replicate, if you have a GPU. See below

Setting both STORAGE_S3_BUCKET and STORAGE_GCS_BUCKET is a misconfiguration and the server refuses to start, on purpose.

Segmentation: your own GPU, or Replicate, or neither

Object extraction has two halves. The click — pick the boulder, see it highlighted — runs in the browser and needs nothing from the server. The sweep — every object in the image at once — runs on a server, and you have three choices:

  • Neither. The default. The sweep is unavailable and says so; the click still works.
  • Replicate. Set REPLICATE_API_TOKEN. About two cents an image, nothing to run, and the image is sent to Replicate for the duration of the call. Users can enter their own token in Settings, which is spent before yours.
  • Your own service. Set SAM2_SERVICE_URL to a running services/sam2-segmentation (its README covers run-local.sh, which auto-detects CUDA). Only worth it with a discrete GPU: on CPU the service is slower than the browser's own WebGPU path on the same machine, so a laptop pointed at itself makes segmentation worse, not better.

SEGMENTATION_PROVIDER=service|replicate|none picks explicitly when both are set. The reasoning behind all of this is in the deployment study.

Docker

docker compose up --build

Brings up the server, PostgreSQL, and Redis. For development with only the supporting services:

docker compose -f docker-compose.dev.yml up -d

Deploying to a cloud

The repository ships Terraform for both AWS (ECS, RDS, S3, CloudFront) and Google Cloud (Cloud Run, Cloud SQL, GCS). See infra/README.md in the source.

This is real infrastructure work. If you only want to play with friends, a single small VM with Docker Compose is far less trouble.

Database migrations

On PostgreSQL, migrations run automatically at server start. A failed migration aborts startup rather than running against a half-migrated schema — that is deliberate. Back up before upgrading.

Your first administrator

There is no UI to create the first admin. Set the flag directly in the database:

UPDATE user_settings SET is_admin = true WHERE clerk_user_id = '‹your clerk user id›';

After that, admins can grant admin to others from the app.

Modules

Which modules your instance loads is configuration. First-party modules are published packages; you can also develop your own.

→ Module Development

Getting help

Self-hosting questions belong on the repository's issue tracker, not with hosted support. Include your Node version, database, storage backend, and the server log around the failure.