cartethyia 0.0.0-stage → 2.3.0

package/.env.example

@@ -0,0 +1,124 @@
+# Required runtime settings.
+# ---------------------------------------------------------------------------
+# Database mode (the one choice that matters):
+#   lite = embedded database, nothing to install (default — just run it).
+#   full = external PostgreSQL via DATABASE_URL (VPS, share/selling, teams).
+# Moving lite → full later is a JSON backup export + import, no rebuild.
+# PORT                  — HTTP port the gateway/console listen on.
+# NODE_ENV              — development | production (affects logging/validation strictness).
+# DASHBOARD_DIST        — built dashboard static directory served at /console.
+# LOG_LEVEL             — pino level: debug / info / warn / error.
+# CARTETHYIA_DB_MODE    — REQUIRED, no default: lite or full. The gateway throws
+#                         at boot when it is absent rather than guessing, because
+#                         the two modes are different databases with separate
+#                         migration sets and a silent guess would pick which one
+#                         an install's data is read against. `bun setup` writes it.
+# DATABASE_URL          — required in full mode only; ignored in lite.
+# CARTETHYIA_ENCRYPTION_KEY
+#                       — required 256-bit secret that encrypts provider credentials
+#                         and API keys. Generate with one of the commands below.
+# CARTETHYIA_PUBLIC_ORIGIN
+#                       — externally reachable URL for OAuth callbacks/links.
+# CARTETHYIA_API_KEY    — optional default gateway API key. Unset means none.
+
+# lite keeps this file the zero-dependency first run: embedded SQLite in the data
+# dir, no server to install. Switch to full for a VPS or shared workload — see the
+# Full section of documentation/getting-started.md.
+CARTETHYIA_DB_MODE=lite
+PORT=12800
+NODE_ENV=development
+DASHBOARD_DIST=./dist/dashboard
+LOG_LEVEL=debug
+# DATABASE_URL=postgres://postgres:replace-with-local-password@localhost:5432/cartethyia
+CARTETHYIA_ENCRYPTION_KEY=replace-with-cartethyia-encryption-key
+CARTETHYIA_PUBLIC_ORIGIN=http://localhost:12800
+
+# How to generate CARTETHYIA_ENCRYPTION_KEY (choose ONE; 32 bytes = 256 bits):
+#   macOS / Linux:  openssl rand -hex 32
+#   Windows (PowerShell):  [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))
+#   Bun / Node (any platform):  bun -e "import { randomBytes } from 'node:crypto'; console.log(randomBytes(32).toString('base64'))"
+# Paste the output as the key value. Either 64-char hex or base64 that decodes to 32 bytes is accepted.
+# The setup/install helpers generate one automatically when the .env is created.
+
+# Optional settings. Redis is never required: set REDIS_URL for shared
+# coordination across instances, or leave it unset for the in-memory backend.
+# REDIS_URL=redis://localhost:6379 # Shared Redis; omit for in-memory.
+# CARTETHYIA_DATA_DIR= # Writable state root. Lite stores <dir>/cartethyia.sqlite; OS default otherwise.
+# TRUSTED_PROXY_CIDRS= # Trust forwarded client-IP headers from these proxy ranges.
+# CARTETHYIA_ALLOWED_NETWORKS= # Private CIDRs allowed for upstream connections.
+# CARTETHYIA_TELEMETRY_PAYLOAD_DIR=./data/telemetry-payloads # Payload capture directory.
+# CARTETHYIA_CONFIG_DIR= # npm CLI only: directory holding .env. OS default otherwise.
+# VITE_BACKEND_URL=http://127.0.0.1:12800 # Backend URL for dashboard development.
+
+# Defaults and overrides. Uncomment only when the built-in default is not suitable.
+
+# Database connection and lock limits.
+# DATABASE_POOL_MAX=20 # Maximum database connections per process.
+# DATABASE_STATEMENT_TIMEOUT_MS=30000 # Maximum statement runtime.
+# DATABASE_IDLE_IN_TXN_TIMEOUT_MS=60000 # Maximum idle transaction time.
+# DATABASE_LOCK_TIMEOUT_MS=5000 # Maximum lock wait time.
+
+# Setup, request limits, memory warning, and graceful shutdown.
+# CARTETHYIA_SETUP_MODE=auto # Native checks by default; docker starts Compose Redis through CARTETHYIA_REDIS_URL.
+# CARTETHYIA_SERVER_MAX_BODY_BYTES=4194304 # Maximum request body size.
+# CARTETHYIA_SERVER_IDLE_TIMEOUT=60 # Idle connection timeout in seconds.
+# CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS=20000 # Time for active requests to finish.
+# CARTETHYIA_DRAIN_TOKEN= # Enables POST /admin/drain; loopback peer plus this token. Unset disables the route.
+# CARTETHYIA_MEMORY_LIMIT_BYTES=536870912 # Explicit memory warning limit.
+
+# Telemetry retention, payload limits, and provider installation identity.
+# CARTETHYIA_TELEMETRY_RETENTION_DAYS=30 # Metadata telemetry retention in days.
+# CARTETHYIA_TELEMETRY_PAYLOAD_MAX_BYTES=33554432 # Combined full-capture limit; 32 MiB.
+# CARTETHYIA_TELEMETRY_PAYLOAD_FILE_MAX_BYTES=268435456 # Backing file size limit.
+# CARTETHYIA_TELEMETRY_PAYLOAD_RETENTION_MS=900000 # Payload retention time.
+# CARTETHYIA_INSTALL_ID_DIR=./data/.cartethyia # Writable installation-id directory.
+
+# Network and abuse policy.
+# CARTETHYIA_ALLOW_PRIVATE_UPSTREAMS=true # Allow private upstream addresses.
+# CARTETHYIA_MAX_REDIRECTS=3 # Maximum upstream redirects.
+# IP_RATE_MAX_PER_WINDOW=240 # Requests per client IP in the rate window.
+# CARTETHYIA_MODEL_STRIKE_THRESHOLD=10 # Invalid requests inside the window before an IP ban.
+# CARTETHYIA_MODEL_STRIKE_WINDOW_MS=1800000 # Sliding window that keeps invalid requests countable.
+# CARTETHYIA_MODEL_BAN_TTL_MS=21600000 # Invalid-model IP-ban duration.
+
+# Upstream deadlines and fallback retry timing.
+# CARTETHYIA_UPSTREAM_TIMEOUT_MS=120000 # Overall upstream request deadline.
+# CARTETHYIA_STREAM_STALL_TIMEOUT_MS=360000 # Maximum stream silence.
+# CARTETHYIA_STREAM_FIRST_CHUNK_TIMEOUT_MS=200000 # Time to first visible chunk.
+# CARTETHYIA_FALLBACK_RETRY_BASE_MS=100 # Minimum fallback retry delay.
+# CARTETHYIA_FALLBACK_RETRY_CAP_MS=2000 # Maximum fallback retry delay.
+# CARTETHYIA_ROUTE_MAX_ATTEMPTS=8 # Per-request candidate dispatch attempt cap.
+
+# Account and proxy-pool cooldowns and socket limits.
+# CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS=900000 # Rate-limit cooldown.
+# CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS=3600000 # Quota cooldown.
+# CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS=120000 # Model-capacity cooldown.
+# CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS=30000 # Temporary error cooldown.
+# CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS=60000 # Unclassified error cooldown.
+# CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS=3600000 # Ceiling an escalated fallback may reach.
+# CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS=300000 # Bare 401/403 backoff, before a named revocation.
+# CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS=300000 # Buddy policy/channel block base backoff.
+# CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS=86400000 # Auto-disable recovery window; 0 restores terminal.
+# CARTETHYIA_POOL_COOLDOWN_MS=120000 # Proxy-pool failure cooldown.
+# CARTETHYIA_PROXY_MAX_SOCKETS=100 # Maximum active proxy sockets.
+# CARTETHYIA_PROXY_MAX_FREE_SOCKETS=20 # Maximum idle proxy sockets.
+
+# Provider-specific overrides. Leave unset unless a different endpoint is required.
+# CARTETHYIA_KIMI_OAUTH_HOST= # Kimi OAuth host override.
+# CARTETHYIA_KIMI_QUOTA_BASE_URL= # Kimi quota API base URL override.
+# CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN= # Enterprise domain; empty uses github.com.
+
+# Optional disposable test services. Keep these in this local env file; no
+# separate test env file is needed. Backend tests require the test DB URL.
+# CARTETHYIA_TEST_DATABASE_URL=postgres://cartethyia_test:cartethyia_test@127.0.0.1:55432/cartethyia_test
+# CARTETHYIA_TEST_REDIS_URL=redis://127.0.0.1:6379
+
+# Dev console admin (read by scripts/dev/*; no runtime reads these).
+# The password signs in through the real console form against the dev database, so it
+# is an operator credential: keep it in your shell or a local env file, never in git.
+# Used by `bun run dev:console-auth` (an authenticated browser for a later agent-browser
+# command) and by scripts/dev/visual-baseline.ts.
+# CARTETHYIA_DEV_ADMIN_USER=admin
+# CARTETHYIA_DEV_ADMIN_PASSWORD=
+# CARTETHYIA_VISUAL_PORT=12900 # Spare port, so a gateway already on 12800 never collides.
+# CARTETHYIA_BROWSER_AGENT= # Path to the agent-browser binary; auto-detected when unset.