.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
# The public package supports only customer mode: dashboard, memory, and managed-service
# clients. Hosted vendor, relay, compute, and worker roles are not distributed here.
ENGRAPHIS_SERVICE_MODE=customer
# 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.

# Update reminder. When on (default), the server checks for a newer Engraphis release
# once a day and surfaces it in the dashboard banner, the startup log, and over MCP.
# The check is fail-silent and cached; set to 0 to disable all update network activity.
# ENGRAPHIS_UPDATE_CHECK=1
# Override the release source. Default: the GitHub releases/latest API for the project
# repo. Accepts any HTTPS endpoint returning a GitHub-release, PyPI, or
# {"version": "...", "url": "..."} JSON payload.
# ENGRAPHIS_UPDATE_URL=
# Point the default GitHub source at a different owner/repo (ignored when
# ENGRAPHIS_UPDATE_URL is set). Default: Coding-Dev-Tools/engraphis.
# ENGRAPHIS_UPDATE_REPO=Coding-Dev-Tools/engraphis

# Optional local API bearer. If set, supported protected routes accept
# Authorization: Bearer <token>. Use a strong, independently revocable value and do not
# reuse a hosted Engraphis credential here.
ENGRAPHIS_API_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

# Code indexing accepts roots under the working, home, or temporary directories by
# default. Set this to replace those defaults with an explicit absolute-path allow-list.
# Separate paths with ";" on Windows or ":" on macOS/Linux.
# ENGRAPHIS_INDEX_ROOTS=/srv/engraphis/repos:/mnt/code
# The dashboard and REST /api/code/index route accept paths only below this one root.
# An explicit root (or the ENGRAPHIS_INDEX_ROOTS fallback entry) must be absolute.
# Defaults to the first ENGRAPHIS_INDEX_ROOTS entry, or the current directory; an
# explicit HTTP root is included in the engine-approved set.
# ENGRAPHIS_HTTP_INDEX_ROOT=/srv/engraphis/repos

# ── 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
# OFF by default (opt-in). While ON, a successful dashboard connection test enables
# llm_structured automatically. Use the Settings "LLM extraction" On/Off button to turn
# it on or off; it 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=0

# ── 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

# 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 local 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"}

# ── Hosted Pro / Team customer client ───────────────────────────────────────
# Cloud Sync, Analytics, Automation, Auto Dreaming, Auto Consolidation, and Team
# administration run on the official private service. These variables configure only the
# public customer client; no setting turns this package into a relay, compute worker, license
# issuer, or Team identity server.
# ENGRAPHIS_CLOUD_CONTROL_URL=https://api.engraphis.com
# ENGRAPHIS_CLOUD_COMPUTE_URL=https://compute.engraphis.com
# ENGRAPHIS_CLOUD_ORGANIZATION_ID=org_replace_me

# Prefer the owner-only ~/.engraphis/cloud_session.json created during hosted onboarding.
# For non-interactive deployments a refresh credential may be injected as a bootstrap secret.
# It rotates on use; the owner-only saved replacement takes precedence afterward, even while
# the environment variable remains set. Never commit it. Bind environment-only bootstrap
# credentials to the subject assigned at onboarding (device or member). A short-lived access
# token is supported for jobs.
# ENGRAPHIS_CLOUD_REFRESH_CREDENTIAL=
# ENGRAPHIS_CLOUD_TOKEN_SUBJECT=member
# ENGRAPHIS_CLOUD_ACCESS_TOKEN=

# Persistent customer state (cloud session and optional saved scoped relay bearer).
# Locally defaults to ~/.engraphis; in a container use a private persistent volume.
# ENGRAPHIS_STATE_DIR=/data/.engraphis

# Hosted entitlements may report a separate local-only write grace capped at 24 hours.
# It never extends the exact 3-day trial, subscription expiry, or any cloud access.

# Managed compute consent. Set to 1 to allow the open package to upload workspace
# snapshots to the Engraphis Cloud service for managed analytics, dreaming, and
# consolidation. Without this flag, managed compute is off and no cloud upload
# occurs. The cloud service is authoritative for all paid computation.
# ENGRAPHIS_MANAGED_COMPUTE_CONSENT=1

# Optional credential-redacted JSON logs for hosted customer deployments.
# ENGRAPHIS_JSON_LOGS=1