.env.example

# ── Engraphis Configuration ──────────────────────────────────────────
# Copy this file to .env and edit only the settings you need. Commented values preserve
# the platform-aware defaults in engraphis/config.py; hosted deployments additionally
# require the authentication and public-URL settings described below.

# ── Server ──────────────────────────────────────────────────────────────────
ENGRAPHIS_HOST=127.0.0.1
ENGRAPHIS_PORT=8700
# customer: dashboard/memory/sync only; vendor: issuance/billing/email only;
# combined: development compatibility mode (never use for either production service).
ENGRAPHIS_SERVICE_MODE=combined
# The dashboard base URL is derived from ENGRAPHIS_HOST:ENGRAPHIS_PORT.
# Set ENGRAPHIS_DASHBOARD_URL for a canonical public HTTPS URL behind a reverse proxy.

# Optional shared service/operations bearer. If set, supported protected routes accept
# Authorization: Bearer <token>; managed backup/readiness automation should use a strong,
# independently revocable value. It does not prove hosted deployment ownership and is not
# entered during trial or first-admin setup (use ENGRAPHIS_DEPLOYMENT_TOKEN there).
ENGRAPHIS_API_TOKEN=

# Hosted deployment ownership secret. Railway customer templates require a unique value
# of at least 32 characters. It starts a deployment-bound trial and authorizes the first
# remote admin setup; it is not an agent token or a vendor credential.
ENGRAPHIS_DEPLOYMENT_TOKEN=

# VENDOR RELAY ONLY — token authorizing vendor-wide license administration on the
# shared relay (/license/v1 revoke, keys-by-email, deactivate, device listing).
# Keep it a SEPARATE secret from ENGRAPHIS_API_TOKEN: the API token is handed to
# scripts/agents as a per-instance service credential and must never be able to
# revoke customers' licenses. REQUIRED for those routes as of 0.9.8 — the old
# fallback to ENGRAPHIS_API_TOKEN was removed (it made the separation above
# meaningless). Unset ⇒ the vendor admin routes are DISABLED, not open. Production
# fails closed unless this is 32-4096 non-whitespace characters (no control ASCII). Generate it:
#   python -c "import secrets; print(secrets.token_urlsafe(48))"
ENGRAPHIS_VENDOR_ADMIN_TOKEN=

# ── Storage ─────────────────────────────────────────────────────────────────
# SQLite database override. Leave commented to use <repo>/engraphis.db from a source
# checkout or the platform user-data directory from an installed wheel.
# ENGRAPHIS_DB_PATH=./engraphis.db

# ── Encryption at rest (optional; SQLCipher / AES-256) ──────────────────────
# Transparently encrypt the ENTIRE memory database file. OFF by default. Needs the extra:
#     pip install "engraphis[encryption]"
# Generate a strong key:  python -c "import secrets; print(secrets.token_hex(32))"
# A 64-hex value is used as a raw 32-byte key; anything else is treated as a passphrase.
# WARNING: lose this key = lose the data (no recovery). In production, inject it from a
# secrets manager (or ENGRAPHIS_DB_KEY_FILE), NOT from this file. An existing PLAINTEXT
# db cannot just be keyed — migrate it (dump → import into a fresh keyed db).
# ENGRAPHIS_DB_KEY=
# ...or read the key from a file (e.g. a mounted docker/k8s secret):
# ENGRAPHIS_DB_KEY_FILE=/run/secrets/engraphis_db_key

# ── Embeddings ──────────────────────────────────────────────────────────────
# Local sentence-transformers model (downloaded on first run, ~80-400 MB).
ENGRAPHIS_EMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Embedding dimension is auto-detected from the model. Override only if needed.
# ENGRAPHIS_EMBED_DIM=384

# ── LLM (external, you choose the provider) ─────────────────────────────────
# Provider: openai | anthropic | google | openrouter | custom
# ── v2 write-path fact extraction (optional) ─────────────────────────────────
# "none" (default): store text as given. "chunk": deterministic offline chunks.
# "llm": free-form fact extraction. "llm_structured": schema-validated typed facts,
# entities, relations, and keywords using the LLM settings below.
ENGRAPHIS_EXTRACTOR=none
# A successful dashboard connection test turns llm_structured on automatically. The
# Settings On/Off button updates the live engine immediately and persists this flag plus
# ENGRAPHIS_EXTRACTOR only when the project .env is writable. Explicit deployment
# environment variables remain authoritative after restart.
ENGRAPHIS_LLM_AUTO_EXTRACT=1

# ── Knowledge-graph extraction (powers the dashboard Graph tab) ──────────────
# "regex" (default): dependency-free heuristic NER runs on every ingest so the Graph tab
# has nodes — no API key, safe offline. "none": disable heuristic text extraction.
# Validated entity/relation metadata from "llm_structured" still feeds the graph
# automatically. Existing memories are backfilled when a workspace graph first opens.
ENGRAPHIS_GRAPH_EXTRACTOR=regex
# Analytical Galaxy is the default; set 0 for the one-release legacy ForceGraph fallback.
ENGRAPHIS_GRAPH_UI_V2=1

# Optional host-LLM retention supervision. "none" preserves the deterministic write path;
# "llm" sends a bounded excerpt to the configured provider for an advisory
# ephemeral/normal/critical signal. Writes are never discarded.
ENGRAPHIS_RETENTION_SUPERVISOR=none

# Optional local resource adapters:
# ENGRAPHIS_WHISPER_MODEL=/absolute/path/to/local-whisper-model
# ENGRAPHIS_WHISPER_DEVICE=auto
# ENGRAPHIS_WHISPER_COMPUTE_TYPE=default
# ENGRAPHIS_POSTGRES_CONNECT_TIMEOUT=10
# ENGRAPHIS_POSTGRES_STATEMENT_TIMEOUT_MS=30000
# ENGRAPHIS_POSTGRES_DSN=postgresql://user:password@localhost/db

# Optional read-only team graph/recall server (`engraphis-graph-server`, port 8720).
# Required when binding that server beyond loopback; falls back to ENGRAPHIS_API_TOKEN.
# ENGRAPHIS_GRAPH_TOKEN=
# ENGRAPHIS_GRAPH_HOST=127.0.0.1
# ENGRAPHIS_GRAPH_PORT=8720

# ── Reverse proxy (TLS termination) ─────────────────────────────────────────
# When behind a proxy that terminates TLS (Railway/Fly/nginx), trust its
# X-Forwarded-Proto/-For headers so request.url.scheme is https and the session
# cookie's Secure flag is set. The default trusts no forwarded headers (safe when the
# port is published directly). Behind a TLS-terminating proxy,
# set this to the proxy's IP/CIDR (or "*" if the container is reachable ONLY via that
# trusted proxy) to enable https scheme detection + the session cookie's Secure flag.
# Trusting "*" on a directly published port lets clients spoof X-Forwarded-For
# (rate-limit bypass / forged audit IP).
# ENGRAPHIS_FORWARDED_ALLOW_IPS=127.0.0.1

# ── Response security headers ───────────────────────────────────────────────
# Every entrypoint sends CSP, X-Frame-Options, X-Content-Type-Options,
# Referrer-Policy, Permissions-Policy, and (over HTTPS only) HSTS. Both variables
# REPLACE the built-in value wholesale; set either to an EMPTY string to omit that
# header entirely, which is what you want when a fronting proxy sets its own.
# The default CSP is strict same-origin and contains no unsafe-inline; dashboard CSS,
# JavaScript, and vendored libraries are served under /static.
# Quote the values — both contain characters a shell would otherwise split on.
# ENGRAPHIS_CSP="default-src 'self'; frame-ancestors 'none'"   # replace the policy
# ENGRAPHIS_CSP=""                                             # send no CSP at all
# ENGRAPHIS_HSTS="max-age=31536000; includeSubDomains"

ENGRAPHIS_LLM_PROVIDER=openai
# Model name (provider-specific):
#   openai:      gpt-4o-mini, gpt-4o, gpt-4.1-mini, o4-mini ...
#   anthropic:   claude-3-5-haiku-20241022, claude-3-5-sonnet-20241022 ...
#   google:      gemini-1.5-flash, gemini-2.0-flash ...
#   openrouter:  anthropic/claude-3.5-sonnet, openai/gpt-4o-mini ...
#   custom:      any model name your OpenAI-compatible endpoint accepts
ENGRAPHIS_LLM_MODEL=gpt-4o-mini
# API key for chat/synthesis, llm/llm_structured extraction, and structured consolidation:
ENGRAPHIS_LLM_API_KEY=sk-your-key-here
# For openrouter / custom: the base URL of the OpenAI-compatible endpoint.
#   openrouter: https://openrouter.ai/api/v1
#   custom:     https://your-endpoint/v1
# ENGRAPHIS_LLM_BASE_URL=https://openrouter.ai/api/v1
# Optional: extra headers (JSON string) for custom providers.
# ENGRAPHIS_LLM_EXTRA_HEADERS={"HTTP-Referer":"https://myapp.com","X-Title":"engraphis"}

# ── Background Consolidation Loop ───────────────────────────────────────────
# Interval (seconds) between background thought-synthesis + reweight cycles.
# Set to 0 to disable the background loop.
ENGRAPHIS_LOOP_INTERVAL=60
# Max memories to consider per namespace per cycle.
ENGRAPHIS_LOOP_TOP_K=20
# Decay half-life in days (Ebbinghaus). Higher = memories persist longer.
ENGRAPHIS_DECAY_HALFLIFE_DAYS=7

# ── License & Team mode (Pro / Team) ────────────────────────────────────────
# Engraphis core is free forever. A signed license key unlocks Pro features
# (analytics, HTML/compliance export, automation, cloud sync) and Team mode
# (multi-user dashboard: per-user logins, roles admin/member/viewer, seats,
# team audit log). A key activates via ANY of: this variable, a one-line file at
# $ENGRAPHIS_STATE_DIR/license.key, or the dashboard's license dialog. Signatures are
# checked locally, but paid features also require a current machine-bound service lease.
# ENGRAPHIS_LICENSE_KEY=ENGR1.xxxxx.yyyyy

# Team mode: per-user logins + roles on the dashboard (engraphis-dashboard binary).
# ON by default. Set ENGRAPHIS_TEAM_MODE=0 to disable (single-user mode). Requires a
# Team license to add seats beyond the first admin; first visit creates the admin.
# ENGRAPHIS_TEAM_MODE=0

# Canonical HTTPS URL of this dashboard. Deployment claims bind this origin, and pending
# invitation emails contain a one-time password-creation link at this origin.
# ENGRAPHIS_DASHBOARD_URL=https://dash.yourcompany.com

# Pending-invitation emails: if THIS instance has its own ENGRAPHIS_RESEND_API_KEY
# or ENGRAPHIS_SMTP_* configured (see the email-delivery section below), it sends
# invites directly from your own address. Otherwise it automatically falls back to
# relaying the invite through the VENDOR's mail provider at your Team license's signed
# license-service URL (or ENGRAPHIS_CLOUD_URL), so a customer-operated sync relay does
# not need vendor mail credentials.

# Vendor-side only: cap on invite emails relayed per license key per day, so one
# key (including a free self-serve trial key — see start-trial below) can't be
# used to spam an open relay through the vendor's account. Default 10 — high
# enough for a real team onboarding, low enough to bound abuse of a free key.
# ENGRAPHIS_TEAM_INVITE_DAILY_CAP=10

# Vendor-side hosted password-reset relay limits. Resets are authenticated by an active
# Pro/Team key, origin-bound to the customer deployment, and queued in the durable outbox.
# ENGRAPHIS_PASSWORD_RESET_DAILY_CAP=20
# ENGRAPHIS_PASSWORD_RESET_RECIPIENT_HOURLY_CAP=5

# Where 402 responses / upgrade banners send users. Set to your real checkout at launch.
# ENGRAPHIS_PRO_UPGRADE_URL=https://buy.polar.sh/<your-pro-product>
# ENGRAPHIS_TEAM_UPGRADE_URL=https://buy.polar.sh/<your-team-product>
# (legacy single-URL alias, still honored): ENGRAPHIS_UPGRADE_URL=

# Persistent state dir (license.key, trial.json, machine_id, lease, relay/registry DB).
# In Docker this is /data/.engraphis (on the volume) so keys/trial/revocations survive
# redeploys. Locally it defaults to ~/.engraphis.
# ENGRAPHIS_STATE_DIR=/data/.engraphis

# ── Cloud sync — automatic (Pro / Team) ─────────────────────────────────────
# Cloud sync always works from the dashboard "Sync now" button and the CLI
# (python -m scripts.sync). In ADDITION, the dashboard can sync in the background on a
# cadence: enable it from Settings → Cloud Sync ("Sync automatically every N min"). It is
# opt-in (off by default), Pro/Team-gated, and the loop no-ops without a licensed key.
# The toggle + cadence persist to autosync.json next to the DB. See docs/SYNC.md.
#
# Kill switch for the in-process background loop (the button/CLI still work). Set to 0 if
# you drive sync purely from cron/pm2 and don't want the dashboard process syncing itself.
# ENGRAPHIS_AUTOSYNC_LOOP=1
# Override where the auto-sync policy is stored (default: next to ENGRAPHIS_DB_PATH).
# ENGRAPHIS_AUTOSYNC_STATE=/data/.engraphis/autosync.json
# Local client credential for the managed relay. Prefer saving it through the dashboard;
# if supplied here, use only a per-user token from /api/auth/token, never a license key.
# ENGRAPHIS_SYNC_TOKEN=engr_ut_replace_me
# ENGRAPHIS_SYNC_READ_ONLY=0
# Temporary customer migration switch; leave off when no legacy customers exist.
# ENGRAPHIS_LEGACY_TEAM_KEY_SYNC=0

# ── Commercial / vendor (ONLY if you SELL Engraphis — not needed to self-host) ──
# Server-side of cloud enforcement + fulfillment. Set these on your vendor host.
#
# Vendor Ed25519 signing seed — signs issued license KEYS and short-lived LEASES.
# 64-char hex inline (how Railway/Fly set it) OR a path to a file with that hex.
# A file must be a regular file no larger than 1 KiB and, on POSIX, owner-only
# (chmod 600); non-regular or group/world-readable targets are refused.
# MUST correspond to the pinned public key in engraphis/licensing.py (_VENDOR_PUBKEY_HEX),
# else every key you issue fails to verify on clients. Verify with:
#   python -m scripts.license_admin verify '<license-key>'
# ENGRAPHIS_VENDOR_SIGNING_KEY=<64-char-hex-seed or /path/to/vendor_signing.key>
#
# Registry + relay + registrations DB (issued keys, revocations, sync bundles, device
# seats). Put it on a PERSISTENT volume or revoked keys un-revoke on restart.
# ENGRAPHIS_RELAY_DB=/data/.engraphis/relay.db
# Durable Polar delivery/order claims and Team seat baselines. This must also live on the
# persistent vendor volume. Vendor-mode backup fails closed if this file or the relay DB is
# absent, so initialize the real stores before enabling the daily backup workflow.
# ENGRAPHIS_WEBHOOK_STATE=/data/.engraphis/polar-webhooks.db
#
# Lease lifetime (hours). Lower = faster revocation takes effect, more phone-home.
# Default 24 (license_registry.LEASE_TTL_HOURS_DEFAULT), floored at 5 minutes.
# ENGRAPHIS_LEASE_TTL_HOURS=24
#
# REQUIRED on the vendor control plane. The public https:// base URL of THIS service, used
# to build the emailed magic-link. There is deliberately no fallback: deriving it from
# the request would mean deriving it from the client-supplied Host header, which let an
# attacker have a victim emailed a confirmation link pointing at attacker-controlled
# infrastructure (fixed 2026-07-18). Unset ⇒ /license/v1/start-trial answers 503.
# ENGRAPHIS_RELAY_PUBLIC_URL=https://license.engraphis.com
# Development-only escape hatch for the pre-GA key-copy trial route. Never enable on the
# production vendor service; readiness and onboarding use /license/v1/trial-claims.
# ENGRAPHIS_ENABLE_LEGACY_TRIAL_FLOW=0
#
# Per-account relay storage ceilings. Defaults 2 GiB / 64 workspaces. The per-workspace
# caps alone bound nothing — workspace ids are caller-supplied — and the relay DB shares
# a volume with the revocation registry, so one trial key filling the disk would break
# license verification for every customer. Set to 0 to disable a check.
# ENGRAPHIS_RELAY_MAX_ACCOUNT_BYTES=2147483648
# ENGRAPHIS_RELAY_MAX_WORKSPACES_PER_ACCOUNT=64
#
# Per-IP burst cap on the unauthenticated key-verifying routes: /license/v1/register,
# /license/v1/team-invite, and /license/v1/password-reset share ONE budget (per minute,
# per process), so alternating
# between them buys no extra work. Guards the ~3 ms pure-Python Ed25519 verify from being
# used as an unauthenticated CPU DoS. 0 disables. Default 60.
# ENGRAPHIS_REGISTER_RATE_PER_MINUTE=60
#
# Per-IP burst cap on the authenticated sync relay's OWN token bucket (one full sync round
# is many requests), kept separate from the register bucket above so sync traffic is not
# throttled by the unauthenticated verify routes. 0 disables. Default 600.
# ENGRAPHIS_RELAY_RATE_PER_MINUTE=600
#
# Polar billing webhook (auto-fulfill: order.paid -> signed key -> email).
# Use Polar's generated value. Raw secrets, or the decoded bytes of legacy whsec_
# values, must contain at least 16 bytes of key material or readiness fails closed.
# POLAR_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx
# POLAR_ORGANIZATION_ID=            # required in vendor production
# These values must match engraphis/commercial_manifest.json exactly. Unknown products
# and wrong-organization events are rejected rather than heuristically fulfilled.
# POLAR_PRO_MONTHLY_PRODUCT_ID=6349d29a-b4c0-4b8e-b9e8-071705351c9c
# POLAR_PRO_ANNUAL_PRODUCT_ID=5e10d5d2-607a-4e9c-ad1c-88cb48c37e11
# POLAR_TEAM_MONTHLY_PRODUCT_ID=6444a48a-7a61-4c8e-8045-07a930f8f381
# POLAR_TEAM_ANNUAL_PRODUCT_ID=929d926a-2981-4ad7-95bd-f52dabf0794e
#
# Outbound email (license-key delivery AND team invite notifications). Resend
# API (preferred) OR SMTP.
# ENGRAPHIS_RESEND_API_KEY=re_xxxxxxxxxxxx
# Use Resend's generated value; its raw/decoded signing key must be at least 16 bytes.
# RESEND_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx
# ENGRAPHIS_SMTP_FROM=licenses@yourdomain.com
# ENGRAPHIS_SMTP_HOST=            # alternative to Resend
# ENGRAPHIS_SMTP_PORT=587
# ENGRAPHIS_SMTP_USER=
# ENGRAPHIS_SMTP_PASSWORD=
#
# ── Client side (end-user machines) ─────────────────────────────────────────
# Paid keys require a revocable, machine-bound lease from the managed service. The
# built-in default is https://license.engraphis.com; override only for a different vendor
# deployment. Free-tier use remains local and does not require the service.
# ENGRAPHIS_CLOUD_URL=https://license.engraphis.com

# Server-side license enforcement (vendor/fulfillment server only): when set, every key
# minted by the Polar webhook carries a signed enforce:"cloud" claim + this URL, and the
# client requires a live lease from it (revocable, seat-counted, useless offline).
# Set this to the canonical managed-service URL for newly issued keys. Older keys carrying
# the retired Railway hostname are migrated by the client without changing their signature.
# ENGRAPHIS_KEY_CLOUD_URL=https://license.engraphis.com

# ── Encrypted commercial backups ────────────────────────────────────────────
# Exact 32-byte key as 64 hex characters, supplied only through the production secret
# store. Mount off-volume storage and schedule scripts/commercial_backup.py daily.
# ENGRAPHIS_BACKUP_KEY=
# ENGRAPHIS_BACKUP_OUTPUT_DIR=/backup/engraphis
# ENGRAPHIS_BACKUP_STATUS_FILE=/data/.engraphis/backup-status.json
# ENGRAPHIS_BACKUP_RETENTION_DAYS=30
# ENGRAPHIS_BACKUP_MAX_AGE_SECONDS=93600
# ENGRAPHIS_CUSTOMER_MIN_FREE_BYTES=268435456
# ENGRAPHIS_REJECTED_LEASE_ALERT_THRESHOLD=50
# ENGRAPHIS_REJECTED_LEASE_ALERT_WINDOW_SECONDS=3600
# Control-plane readiness fails when pending/retrying mail is too old, a message exhausts
# retries, or the 24-hour bounce/complaint rate is too high after the minimum sample size.
# ENGRAPHIS_EMAIL_MAX_BACKLOG_AGE_SECONDS=900
# ENGRAPHIS_EMAIL_MAX_BOUNCE_RATE=0.05
# ENGRAPHIS_EMAIL_BOUNCE_MIN_SAMPLE=20
# ENGRAPHIS_JSON_LOGS=1
# Customer deployments with local Resend/SMTP retry durable email every 30 seconds.
# ENGRAPHIS_EMAIL_OUTBOX_LOOP=1
# Example (destination must be a separate mounted device in production):
# python -m scripts.commercial_backup backup --output-dir /backup/engraphis \
#   --marker /data/.engraphis/backup-status.json --retention-days 30