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.
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/landingpages/app.html: agent creatorpages/agent-edit.html,pages/agent-embed.html: agent pages (/agent/:iditself 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_SECRETis generated withopenssl rand -base64 64(never a short or guessable string) -
DATABASE_URLincludes?sslmode=require -
PUBLIC_APP_ORIGINis 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
originlist - All environment variables are set on the Cloud Run service (
three-ws-api), verified withgcloud run services describe -
AGENT_RELAYER_KEYis set via the Cloud Run service env vars, not committed to git -
.mcp.jsondoes not contain a real API key if checked into git -
JWT_KIDis set so key rotation can be performed without invalidating all sessions
Related
- Deployment & Self-Hosting: how to run the stack in production
- Security: the security model these settings feed into
- Contributing: local development workflow and test commands