# ============================================================================= # Gitgram TimeMachine API Server - Environment Variables # ============================================================================= # Copy this file to .env and fill in the values. # Variables marked [REQUIRED] must be set for the server to start. # All others are optional with sensible defaults. # ============================================================================= # ── Core ───────────────────────────────────────────────────────────────────── # Runtime environment: development | staging | production | test NODE_ENV=development # HTTP host the Express server binds to (127.0.0.1 for local, 0.0.0.0 for container) HOST=127.0.0.1 # HTTP port the Express server listens on PORT=3001 # Set to 1 to boot app modules without opening a network port (CI/sandbox checks) # AITM_TEST_NO_LISTEN=1 # ── Database [REQUIRED] ───────────────────────────────────────────────────── # PostgreSQL connection string. # Works with both Neon and standard Postgres: # Neon: postgresql://user:password@host/database?sslmode=require # Local: postgresql://gitgram:gitgram_dev@localhost:5432/gitgram DATABASE_URL=postgresql://gitgram:gitgram_dev@localhost:5432/gitgram # ── Networking ─────────────────────────────────────────────────────────────── # Allowed CORS origin(s); set to specific domain in production CORS_ORIGIN=http://localhost:3000 # AITM website URL (used for redirects, billing success pages, emails) WEBSITE_URL=http://localhost:3000 # ── Auth ───────────────────────────────────────────────────────────────────── # Shared secret for website-to-API internal calls INTERNAL_SECRET=your-internal-secret-here # Dedicated maintainer collector secret. Required in staging/production; use a # random value of at least 32 characters. Set PREVIOUS only during rotation. ADOPTION_INGESTION_SECRET=replace-with-a-random-32-plus-character-secret # ADOPTION_INGESTION_SECRET_PREVIOUS= OSS_COVERAGE_MAX_AGE_HOURS=168 # JWT signing secret (for session tokens) # JWT_SECRET= # Clerk webhook secret (for user sync from Clerk) # CLERK_WEBHOOK_SECRET= # ── AWS / S3 ───────────────────────────────────────────────────────────────── # AWS region (default: us-east-1) AWS_REGION=us-east-1 # AWS IAM credentials (leave blank to use SDK default credential chain) # AWS_ACCESS_KEY_ID= # AWS_SECRET_ACCESS_KEY= # S3 bucket for knowledge base blobs # KB_S3_BUCKET= # Key prefix inside KB bucket (default: knowledge-base) KB_S3_PREFIX=knowledge-base # Content size thresholds (bytes) KB_MAX_CONTENT_BYTES=500000 KB_MAX_FILE_BYTES=1048576 KB_S3_THRESHOLD_BYTES=102400 # Embedding generation KB_EMBEDDINGS_ENABLED=true KB_EMBEDDING_MAX_BYTES=100000 # ── Polar.sh Billing ──────────────────────────────────────────────────────── # Get from https://polar.sh/dashboard # Use sandbox for local/staging testing, production for live billing. POLAR_ACCESS_TOKEN= POLAR_MODE=sandbox POLAR_WEBHOOK_SECRET= POLAR_PRO_PRODUCT_ID= POLAR_TEAM_PRODUCT_ID= # ── Email (Resend) ────────────────────────────────────────────────────────── # Get API key from https://resend.com/api-keys # Falls back to console logging when not set # RESEND_API_KEY=re_... # ── Monitoring ─────────────────────────────────────────────────────────────── # Sentry DSN for error tracking (optional) # SENTRY_DSN= # Logging level: debug | info | warn | error (default: debug in dev, info in prod) # LOG_LEVEL= # API version string reported in health endpoint API_VERSION=1.0.0 # ── LLM / AI ──────────────────────────────────────────────────────────────── # REQUIRED for AI features. At least one LLM key is needed for AI features # (oracle summaries, checkpoint-name suggestions, research). Without a key, # AI features degrade to deterministic heuristics and llm.complete() returns a # clear "AI features are unavailable" placeholder. Check status at # GET /health/providers (the "LLM" entry reports "unconfigured" when unset). # OPENAI_API_KEY=sk-... # ANTHROPIC_API_KEY=sk-ant-... # ── Embeddings (semantic search) ───────────────────────────────────────────── # REQUIRED for production-grade semantic ranking. Knowledge-base / context / # package-search semantic ranking uses an embedding provider. When neither key # below is set, the server falls back to a deterministic LOCAL lexical embedding # (real word/stem/bigram overlap signal, but no synonymy/paraphrase). Configure # a provider for meaningful semantic ranking out of the box. OPENAI_API_KEY # above also serves embeddings (text-embedding-3-small); VOYAGE_API_KEY uses # voyage-code-2. Check status at GET /health/providers ("Embeddings" entry # reports "degraded" while on the local fallback). # VOYAGE_API_KEY= # ── GitGram social bridge (optional integration) ───────────────────────────── # REQUIRED to activate the gitgram<->aitm social push flow (sessions/checkpoints # pushed to the social layer). When GITGRAM_API_URL is unset the bridge defaults # to http://localhost:4000 and the push flow is INERT in a typical production # deploy — a startup warning is logged and GET /health/providers reports the # "GitgramBridge" entry as "unconfigured". GITGRAM_API_KEY additionally gates # restore-event push. # GITGRAM_API_URL=https://api.gitgram.example.com # GITGRAM_API_KEY= # ── First-party engines (beads, git, pal) ──────────────────────────────────── # Engines are built by scripts/build-engines.sh into aitimemachine/bin and # aitimemachine/engines. The Docker image builds them; for non-Docker deploys # the `prestart` hook (scripts/ensure-engines.mjs) auto-builds any missing # engine before `npm start`. Set AITM_SKIP_ENGINE_BUILD=1 to skip (e.g. images # that ship prebuilt binaries without a build toolchain). Status: # GET /health/engines. # AITM_SKIP_ENGINE_BUILD= # BEADS_BINARY= # AITM_GIT_BIN= # PAL_VENV_DIR= # PAL_PYTHON= # ── Web Search ─────────────────────────────────────────────────────────────── # At least one search provider key enables web search # BRAVE_SEARCH_API_KEY= # SERPAPI_KEY= # SERPER_API_KEY= # FIRECRAWL_API_KEY= # ── Data Privacy ───────────────────────────────────────────────────────────── # If true, require explicit user consent before collecting data REQUIRE_EXPLICIT_CONSENT=false # ── Redis (optional) ──────────────────────────────────────────────────────── # Used for distributed rate limiting. Falls back to in-memory when not set. # REDIS_URL=redis://localhost:6379 # ── Background Workers ────────────────────────────────────────────────────── # Set ENABLE_WORKERS=true to use the managed cron-based scheduler. # When false (default), falls back to legacy interval-based workers. ENABLE_WORKERS=false # Cron schedules (only used when ENABLE_WORKERS=true) # Format: minute hour day-of-month month day-of-week RETENTION_CRON=0 3 * * * DELETE_CRON=*/5 * * * * GC_CRON=0 4 * * 0 # Delete worker settings DELETE_WORKER_ENABLED=false DELETE_WORKER_LIMIT=50 DELETE_WORKER_DRY_RUN=false # DELETE_WORKER_USER_ID= # Retention worker settings RETENTION_WORKER_ENABLED=false # RETENTION_WORKER_LIMIT=100 # RETENTION_WORKER_DRY_RUN=false # RETENTION_WORKER_PROJECT_ID= # RETENTION_WORKER_USER_ID= # RETENTION_WORKER_DATA_CLASS= # GC worker settings GC_WORKER_ENABLED=false # GC_WORKER_LIMIT=200 # GC_WORKER_DRY_RUN=false # GC_WORKER_OLDER_THAN_DAYS=30 # GC_WORKER_USER_ID=