Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

26.5 KB
Raw Blame

Configuration Reference

three.ws is configured through a combination of environment variables and a handful of configuration files. This document is a complete reference for self-hosters and developers setting up a local development environment. If you only use the hosted site at three.ws, none of this applies to you; if you are running the code yourself, start with the Minimum Local Development Configuration and come back for the rest as you enable features.

Configuration files at a glance:

File Purpose
.env.local Local development secrets and API keys
vercel.json Routing, cron jobs, and response headers
vite.config.js Build targets and dev server rewrites
cors.json CORS policy applied to your S3/R2 bucket
.mcp.json MCP server connection for Claude Code integration

Environment Variables

Copy .env.example to .env.local for local development. In production, three.ws runs on Google Cloud Run (service three-ws-api, region us-central1) — set these on the Cloud Run service, e.g. gcloud run services update three-ws-api --region us-central1 --update-env-vars NAME=value, or through the Cloud Console. See the full production runbook in docs/ops/gcp-production.md.

cp .env.example .env.local

Core

PUBLIC_APP_ORIGIN

Required for self-hosted deployments. The canonical origin of your deployment, with no trailing slash. When unset, the code falls back to https://three.ws (api/_lib/env.js), which is wrong for any other domain.

PUBLIC_APP_ORIGIN=https://yourdomain.com

Used to construct absolute URLs in API responses and OAuth metadata (exposed to server code as env.APP_ORIGIN). Must match your production domain exactly.

DATABASE_URL

Required. PostgreSQL connection string using Neon's serverless HTTPS driver.

DATABASE_URL=postgres://user:[email protected]/neondb?sslmode=require

Get from: Neon (free tier works for development), Supabase, or any PostgreSQL host. Always include ?sslmode=require in production.

After setting this, provision the schema:

npm run db:bootstrap

This runs all four provisioning steps (core schema + indexer + delegations + migrations) and is idempotent — safe to re-run. Do not apply api/_lib/schema.sql alone: the base schema does not create the migration-defined tables and leaves a half-provisioned database (see deployment.md).

JWT_SECRET

Required. Long random secret used for two purposes: signing session JWTs and (via HKDF) deriving the AES-256-GCM key that encrypts agent wallet private keys.

JWT_SECRET=<base64 string>

Generate with:

openssl rand -base64 64

Rotation: add a new key ID (JWT_KID), wait for old tokens to expire, then remove the old value. Never remove the active signing key mid-rotation.

JWT_KID

Optional. Active key identifier for future key rotation. Defaults to k1.

JWT_KID=k1

PASSWORD_ROUNDS

Optional. bcryptjs cost factor for password hashing. Defaults to 11.

PASSWORD_ROUNDS=11

Higher values increase security at the cost of login latency. 11 is a reasonable default for modern hardware.


LLM

/api/chat routes across a provider failover ladder (see the routing policy comment at the top of api/_lib/llm.js): free-tier providers lead, paid keys are the last-resort tail. No key is required to enable agent conversations at all. A handful of lanes need no key or account and are always in the chain, so /api/chat works out of the box on a fresh clone: Kilo Code's free pool, OVH AI Endpoints' anonymous tier, Pollinations, and LLM7.io. The keys below are entirely about raising the ceiling: more quota, higher-capability models, and a paid backstop so the chain never actually errors.

GROQ_API_KEY

Recommended. Free-tier Groq key; the first keyed provider in the chat ladder, ahead of the always-on keyless lanes.

GROQ_API_KEY=gsk_xxxxx

CEREBRAS_API_KEY

Optional. Cerebras free-tier key, a second independent free lane tried alongside Groq.

OPENROUTER_API_KEY

Optional. OpenRouter key, tried after Groq and Cerebras (the paid model first, then the :free variant on the same key). Backs up every LLM surface; fund it if you rely on paid-model failover.

OPENROUTER_API_KEY=sk-or-xxxxx

GEMINI_API_KEY

Optional. Gemini AI Studio's free tier, another independent free lane.

NVIDIA_API_KEY

Optional. NVIDIA NIM free tier: three Nemotron models (Super, Ultra, Lightning) on one key, each its own NIM function so one model's throttle or retirement is not the whole lane's.

SAMBANOVA_API_KEY, MISTRAL_API_KEY, ZAI_API_KEY

Optional. Three more keyed free lanes: SambaNova Cloud, Mistral's Experiment tier, and Z.AI's GLM Flash lane. Each joins the ladder only when its key is present, so /api/chat degrades across providers without a code change. The server-side completion chain in api/_lib/llm.js also accepts optional Cloudflare Workers AI (CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_AI_API_TOKEN), SiliconFlow, and KILO_API_KEY (raises Kilo's keyless rate limit; the lane itself needs no key) on the same free-first rule.

GOOGLE_CLOUD_PROJECT

Set automatically on every Cloud Run deploy. When present, Gemini Flash-Lite on Vertex sits between the free tiers and the paid tail as the reliability anchor: service-account auth, billed to the platform's GCP credits, no third-party quota to exhaust. Self-hosting outside Cloud Run and want this rung too? Set it to a GCP project with the Vertex AI API enabled and application-default credentials available to the process.

ANTHROPIC_API_KEY

Optional (paid backstop). Anthropic key, appended to the tail of every chain so a request that exhausted every free lane still succeeds instead of erroring. Also accepted as a user-supplied BYOK key, which leads the chain on the caller's own billing.

ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

Get from console.anthropic.com. OPENAI_API_KEY fills the same paid-backstop role for OpenAI, and GROK_API_KEY (alias XAI_API_KEY) adds xAI Grok as the last paid rung; when it is unset the Grok rungs are skipped and only a user's own BYOK Grok key works. watsonx (WATSONX_API_KEY plus a project scope) is served only on explicit request, never as a silent default.

CHAT_MODEL

Optional. Pin a default chat model by id. It only applies when the provider that serves that model id (per the model catalog) is the one routed to; every other provider keeps its own default, so an Anthropic-style model id never leaks into a Groq request.

CHAT_MODEL=claude-sonnet-4-6

CHAT_MAX_TOKENS

Optional. Cap on tokens per chat response. Defaults to 1024.

CHAT_MAX_TOKENS=1024

Storage (S3-Compatible)

All four S3 variables are required to enable GLB file and thumbnail uploads. The service is S3-compatible and works with AWS S3, Cloudflare R2, Backblaze B2, and MinIO.

S3_ENDPOINT

Required for non-AWS providers. Full URL of the S3-compatible endpoint.

S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com

Leave blank for standard AWS S3.

S3_ACCESS_KEY_ID

Required. Access key for your S3-compatible bucket.

S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

S3_SECRET_ACCESS_KEY

Required. Secret key for your S3-compatible bucket.

S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

S3_BUCKET

Required. Bucket name where avatars and assets are stored.

S3_BUCKET=3d-agent-avatars

S3_PUBLIC_DOMAIN

Required. Public CDN base URL for the bucket. Used to construct asset URLs in API responses.

S3_PUBLIC_DOMAIN=https://cdn.yourdomain.com

Use a custom domain for zero-egress delivery (Cloudflare R2 charges no egress on custom domains).

After setting up the bucket, apply the CORS policy — see the cors.json section below.


Cache and Rate Limiting

UPSTASH_REDIS_REST_URL

UPSTASH_REDIS_REST_TOKEN

Recommended for production. Upstash Redis for distributed rate limiting across serverless function instances.

UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=xxxxx

Get from upstash.com. Without Redis, rate limiting falls back to per-instance in-memory state — ineffective in a multi-instance serverless environment and a security risk in production.

UPSTASH_CACHE_REST_URL

UPSTASH_CACHE_REST_TOKEN

Optional, recommended at scale. A second, dedicated Upstash store for the best-effort response caches (galaxy feed, pulse, agent/explore lists, provider health). The variables above back the fail-closed rate limiter; the caches write much larger bodies. On a single shared free store those large writes contend for connections and burn the limiter's command quota — the cause of the redis SET failed … aborted due to timeout warnings on /api/galaxy/flows.

UPSTASH_CACHE_REST_URL=https://yyy.upstash.io
UPSTASH_CACHE_REST_TOKEN=yyyyy

Provision a separate store co-located with your production Cloud Run region (us-central1; cross-region latency is what pushes large SETs past the 3s client timeout). When unset, the cache transparently falls back to the rate-limiter store, then to in-memory — no behavior change. Verify the cutover on the Upstash dashboard: command traffic shifts to the new store and the limiter store's usage drops.


Authentication

VITE_PRIVY_APP_ID

PRIVY_APP_ID

Optional. Privy app ID for social/email login. Two variables are needed: VITE_PRIVY_APP_ID is used client-side (embedded in the built JS), and PRIVY_APP_ID is used server-side to verify identity tokens in /api/auth/privy/verify.

VITE_PRIVY_APP_ID=clxxxxxxxx
PRIVY_APP_ID=clxxxxxxxx

Both should be the same value. Get from dashboard.privy.io.

GOOGLE_OAUTH_CLIENT_ID

GOOGLE_OAUTH_CLIENT_SECRET

Optional. OAuth client for "Sign in with Google" (authorization code + PKCE, /api/auth/google/*): links Google to an existing account, then signs in with it. Create a "Web application" OAuth client in the Google Cloud console with the redirect URI ${PUBLIC_APP_ORIGIN}/api/auth/google/callback. When unset, the Google sign-in buttons stay hidden and the routes answer unconfigured.

GOOGLE_OAUTH_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=xxxxx

Avatar Pipeline

VITE_CHARACTER_STUDIO_URL

Optional. Override for the origin where the three.ws avatar builder is hosted. When unset, the app resolves it same-origin to <origin>/avatar-studio (the Vite dev middleware serves character-studio/build there in dev; the build copies the same bundle to /avatar-studio in production). Set this only to point at a standalone studio dev server (e.g. http://localhost:5173 while developing character-studio/).

VITE_CHARACTER_STUDIO_URL=http://localhost:5173

The three.ws avatar builder is an open-source 3D avatar editor (full body customisation — hair, clothing, accessories, skin tone, proportions). It runs as a separate Vite/React app under character-studio/ in this monorepo and posts the exported GLB back to the parent via postMessage. It is fully compatible with the three.ws avatar runtime — same humanoid skeleton naming, ARKit viseme_* blendshapes, and Mixamo animation support.

AVATURN_API_KEY

Optional. API key for the photo-to-avatar pipeline. Used server-side by /api/onboarding/avaturn-session (api/onboarding/[action].js) to exchange selfie photos for a session URL.

AVATURN_API_KEY=xxxxx

Sign up through the Avaturn developer docs.

AVATURN_API_URL

Optional. Override for self-hosted or staging photo pipeline deployments. Defaults to https://api.avaturn.me.

AVATURN_API_URL=https://api.avaturn.me

VITE_AVATURN_EDITOR_URL, VITE_AVATURN_DEVELOPER_ID

Retired; no code reads them. Both still appear in .env.example, but the photo pipeline no longer builds an editor URL in the browser: src/avatar-creator.js opens the @avaturn/sdk editor against the session URL that /api/onboarding/avaturn-session mints server-side from AVATURN_API_KEY. Setting either variable changes nothing.

AVATAR_REGEN_PROVIDER

Optional. Platform provider for avatar regeneration and reconstruction: replicate, huggingface, or gcp (api/_lib/regen-provider.js). When unset the provider is inferred from credentials, paid first: REPLICATE_API_TOKEN selects Replicate, then GCP_RECONSTRUCTION_URL the self-hosted Cloud Run worker, then HF_TOKEN the HF Spaces queue; TRIPO_API_KEY adds Tripo as a last house-key lane for avatar auto-rig (it is never inferred as the primary); with none of those the platform provider is none and the reconstruct endpoint falls back to a user's stored BYOK key (Meshy, Tripo) before answering 501.

AVATAR_REGEN_PROVIDER=replicate

Blockchain and Permissions

PERMISSIONS_RELAYER_ENABLED

Optional. Enables the server-side ERC-7710 delegation relayer endpoint (POST /api/permissions/redeem). Defaults to false.

PERMISSIONS_RELAYER_ENABLED=false

AGENT_RELAYER_KEY

Conditional. Hex private key of the relayer EOA that pays gas for redeemDelegations. Required when PERMISSIONS_RELAYER_ENABLED=true. This is the server's relayer key, not a user key.

AGENT_RELAYER_KEY=0x...

Generate a fresh wallet:

node -e "const {Wallet} = require('ethers'); const w = Wallet.createRandom(); console.log(w.privateKey, w.address)"

Never commit a real value. Rotate via the Cloud Run service env vars (gcloud run services update three-ws-api --region us-central1 --update-env-vars AGENT_RELAYER_KEY=…).

AGENT_RELAYER_ADDRESS

Conditional. EIP-55 checksummed address derived from AGENT_RELAYER_KEY. Fund with testnet ETH before enabling the relayer.

AGENT_RELAYER_ADDRESS=0x...

RPC_URL_<CHAINID>

Optional. Per-chain RPC URL overrides. Pattern: RPC_URL_ followed by the chain ID. Defaults to public RPC endpoints, which are less reliable under load.

RPC_URL_84532=https://sepolia.base.org        # Base Sepolia
RPC_URL_11155111=https://rpc.sepolia.org      # Ethereum Sepolia

Use Alchemy or Infura URLs in production for reliable RPC access.


IPFS Pinning

At least one pinning provider is needed to enable on-chain avatar registration via IPFS.

PINATA_JWT

Optional (preferred). JWT for IPFS pinning via Pinata.

PINATA_JWT=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Get from app.pinata.cloud/keys.

WEB3_STORAGE_TOKEN

Optional (fallback). Token for IPFS pinning via Web3.Storage (legacy v1 API).

WEB3_STORAGE_TOKEN=xxxxx

Solana signer keys (*_SECRET_KEY_B64)

Optional. Server-side Solana keypairs the cron jobs and on-chain flows sign with, for example PUMP_CRON_RELAYER_SECRET_KEY_B64 (pays tx fees for the Pump.fun buyback cron), COIN_TREASURY_SECRET_KEY_B64, THREE_BUYBACK_SECRET_KEY_B64, CLUB_SOLANA_TREASURY_SECRET_KEY_B64, and PUMP_X402_LAUNCHER_SECRET_KEY_B64. The roster keeps growing (launch sponsorship, fee bridging, and more each added their own signer): read the SOLANA_SIGNERS array in api/_lib/solana-signers.js for the current full list and each one's purpose rather than trusting an enumeration quoted in prose. Each is the base64 encoding of the 64 raw secret-key bytes, the format decodeSecretKey expects.

PUMP_CRON_RELAYER_SECRET_KEY_B64=<base64 of 64-byte keypair>

Generate with the bundled, dependency-free generator (no @solana/web3.js install needed):

# Writes the secret to .env and prints the public key to fund with SOL
node scripts/gen-solana-signer-key.mjs --var PUMP_CRON_RELAYER_SECRET_KEY_B64 --write

# Or print to stdout (swap the var for any of the *_SECRET_KEY_B64 names)
node scripts/gen-solana-signer-key.mjs --var COIN_TREASURY_SECRET_KEY_B64

# Grind a vanity public key (case-insensitive prefix; base58 has no 0/O/I/l)
node scripts/gen-solana-signer-key.mjs --vanity www

Fund the printed public key with SOL before the relayer can pay fees. --write refuses to clobber an existing value, so rotating means removing the old line first. In production a relayer key is a credential, so it goes in Secret Manager rather than on the service as a literal: node scripts/migrate-plaintext-secrets.mjs --only <NAME> --apply moves an existing one, and docs/ops/wallet-key-migration.md has the commands for publishing a new version. Never commit the secret. Read production's current value with node scripts/read-service-env.mjs '^<NAME>$' --raw; a vercel env pull export returns empty for secret-type vars and must not be trusted.


Minimum Local Development Configuration

The smallest .env.local that runs the dev server with core features:

PUBLIC_APP_ORIGIN=http://localhost:3000
DATABASE_URL=postgres://user:[email protected]/neondb?sslmode=require
JWT_SECRET=<output of: openssl rand -base64 64>
GROQ_API_KEY=gsk_...          # or any other chat provider key (see LLM above)
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET=3d-agent-avatars
S3_PUBLIC_DOMAIN=https://cdn.yourdomain.com

Avatar creation, blockchain features, and IPFS are all optional for local development.


vercel.json

A live configuration file consumed at runtime by the Cloud Run server (server/index.mjs), not a Vercel leftover. The server reads its routes array (route table, security headers, rewrites) on boot; the crons list is read by scripts/create-gcp-scheduler.mjs to sync the Cloud Scheduler jobs (the server itself never reads it). The routes array maps incoming URL patterns to destination files or API handlers.

Key route patterns:

{ "src": "/agents/([^/.]+)/edit",  "dest": "/agent-edit.html" }
{ "src": "/agents/([^/.]+)/embed", "dest": "/agent-embed.html" }
{ "src": "/agent/([^/]+)/edit",  "dest": "/agent-edit.html" }
{ "src": "/agent/([^/]+)/embed", "dest": "/agent-embed.html" }
{ "src": "/agent/([^/]+)",       "status": 301, "headers": { "Location": "/agents/$1" } }
{ "src": "/a/(\\d+)/(\\d+)",    "dest": "/api/a-page?chain=$1&id=$2" }
{ "src": "/dashboard/?",         "dest": "/dashboard-next/index.html" }
{ "src": "/studio",              "dest": "/studio/index.html" }

Embed routes (both the /agents/:id/embed and legacy /agent/:id/embed spellings) include security headers that allow cross-origin iframe embedding while still allowlisting the specific third-party scripts the embed loads:

{
  "src": "/agent/([^/]+)/embed",
  "headers": {
    "content-security-policy": "frame-ancestors *; base-uri 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://unpkg.com https://esm.sh https://ajax.googleapis.com https://s3.tradingview.com https://platform.twitter.com https://three.ws; worker-src 'self' blob:; report-uri /api/client-errors",
    "x-content-type-options": "nosniff",
    "referrer-policy": "strict-origin-when-cross-origin",
    "permissions-policy": "microphone=(self), camera=(self), xr-spatial-tracking=*",
    "cross-origin-resource-policy": "cross-origin"
  },
  "dest": "/agent-embed.html"
}

The script-src allowlist grows as the embed adopts new CDNs; read the live entry in vercel.json rather than trusting this list to stay exhaustive.

Versioned CDN routes for the web component library serve immutable assets with long cache TTLs:

{
  "src": "/agent-3d/([0-9]+\\.[0-9]+\\.[0-9]+(?:-[A-Za-z0-9.-]+)?)/(.*)",
  "headers": { "cache-control": "public, max-age=31536000, immutable" },
  "dest": "/agent-3d/$1/$2"
}

These routes also send access-control-allow-origin: * and cross-origin-resource-policy: cross-origin so any site can load the bundle. The moving channels (latest, a major like 1, or a minor like 1.5) get a short cache instead (max-age=3600, s-maxage=300). A miss under a version path (one that has not been released yet) answers 404 without the immutable policy, so a CDN edge does not keep serving that 404 after the version is cut. The UMD build (agent-3d.umd.cjs) is served as text/javascript, so it runs from a plain <script> tag.

Cron jobs are declared here as the source of truth for the schedule. Read the crons array itself for the current set rather than trusting a count quoted in prose. In production they are driven by Google Cloud Scheduler, each job hitting its /api/cron/* handler on the Cloud Run service:

"crons": [
  { "path": "/api/cron/erc8004-crawl",      "schedule": "*/15 * * * *" },
  { "path": "/api/cron/index-delegations",  "schedule": "*/5 * * * *" },
  { "path": "/api/cron/run-dca",            "schedule": "0 * * * *" },
  { "path": "/api/cron/run-subscriptions",  "schedule": "0 * * * *" }
]

These only run against the production deployment (Cloud Scheduler → Cloud Run), not locally. A cron added to this array gets its Scheduler job on the next deploy: npm run deploy:gcp:sync-crons (part of npm run deploy:gcp) creates a job for every declared cron that has none and never touches existing jobs. See docs/ops/gcp-production.md for how the Scheduler jobs are provisioned.


vite.config.js

The build is controlled by the TARGET environment variable:

Command TARGET Output Description
npm run build app (default) dist/ Full multi-page SPA
npm run build:lib lib dist-lib/ Self-contained web component for CDN (ES module only)
npm run build:lib:full lib dist-lib/ The same bundle in both ES and UMD form (LIB_FORMATS=es,umd); this is what build:gcp runs
npm run build:all both both Builds the chat bundle first, then app and lib in parallel

App build (TARGET=app) emits many HTML entry points for the multi-page app, sourced from pages/:

  • pages/home.html: marketing/landing
  • pages/app.html: agent creator
  • pages/agent-edit.html, pages/agent-embed.html: agent pages (/agent/:id itself 301-redirects to /agents/:id)
  • pages/dashboard-next/: user dashboard (sub-pages auto-discovered)
  • public/studio/index.html: widget studio

Library build (TARGET=lib) emits a self-contained ES module. The UMD bundle is opt-in through LIB_FORMATS, which is why the deploy chain runs npm run build:lib:full (TARGET=lib LIB_FORMATS=es,umd) rather than build:lib:

dist-lib/agent-3d.js       # ES module (npm run build:lib)
dist-lib/agent-3d.umd.cjs  # UMD, CommonJS-compatible (npm run build:lib:full)

Three.js and ethers are bundled (not externalized) so the web component works as a zero-install drop-in embed via <script type="module">.

VitePWA generates a service worker for the app build. Only **/*.{ico,woff2}, offline.html and pwa-icon.svg (the offline shell) are precached; HTML pages, JS, and CSS are deliberately excluded so deploys take effect immediately. Google Fonts are cached with a CacheFirst strategy and a 1-year TTL, and /api/* is never intercepted by the service worker.

The dev server includes a rewrite middleware that mirrors the vercel.json route patterns, so http://localhost:3000/agent/my-agent/edit works the same as in production.


cors.json

This file defines the CORS policy for your S3-compatible storage bucket — it is not applied to the API server. Apply it to your bucket using the AWS CLI (or equivalent):

aws s3api put-bucket-cors \
  --bucket 3d-agent-avatars \
  --cors-configuration file://cors.json \
  --endpoint-url https://<account-id>.r2.cloudflarestorage.com

The checked-in cors.json restricts GET requests to a specific list of origins: https://three.ws, the localhost dev origins, and a few existing partner origins:

[
  {
    "method": ["GET"],
    "origin": [
      "https://three.ws",
      "http://localhost:*",
      "https://localhost:*"
    ],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]

Add your own domain to the origin array before applying. At minimum, claude.ai must be included if you want the MCP render_avatar tool to fetch GLBs from your bucket inside Claude.

For a fully open public platform where any site can embed agent viewers, set "origin": ["*"].


.mcp.json

Configures MCP server connections for Claude Code integration. Claude Code auto-discovers this file from the project root. The checked-in file defines four servers (meshy, 3d-agent, 3d-agent-local, atelier); secrets are never inlined — values use ${VAR} environment-variable interpolation, resolved from your shell at load time.

The minimal hosted-endpoint entry looks like:

{
  "mcpServers": {
    "3d-agent": {
      "url": "https://three.ws/api/mcp",
      "headers": {
        "Authorization": "Bearer ${THREE_WS_MCP_TOKEN}"
      }
    }
  }
}

Set THREE_WS_MCP_TOKEN in your environment to an API key from your dashboard. For local development, point url at http://localhost:3000/api/mcp.

Never commit a real API key in this file — keep the ${VAR} interpolation form so the checked-in file stays secret-free.


Production Checklist

Before going live, verify the following:

  • JWT_SECRET is generated with openssl rand -base64 64 (never a short or guessable string)
  • DATABASE_URL includes ?sslmode=require
  • PUBLIC_APP_ORIGIN is set to your production domain (no trailing slash)
  • Upstash Redis is configured — rate limiting is per-instance in-memory without it
  • S3 bucket CORS policy is applied with your production domain in the origin list
  • All environment variables are set on the Cloud Run service (three-ws-api), verified with gcloud run services describe
  • AGENT_RELAYER_KEY is set via the Cloud Run service env vars, not committed to git
  • .mcp.json does not contain a real API key if checked into git
  • JWT_KID is set so key rotation can be performed without invalidating all sessions

Related