Copy .env.example to .env and edit it. This is the complete file for v0.13.6; lines starting with # are optional examples.
Copy this file to .env and add your own Gemini API key. RagLeap Core is bring-your-own-key only — there is no system-provided key. Get a free Gemini API key at: https://aistudio.google.com/apikey
GEMINI_API_KEY=your-gemini-api-key-here
GEMINI_EMBEDDING_MODEL=models/gemini-embedding-001
EMBEDDING_DIMENSIONS=3072
Embedding provider: gemini (default) | ollama | openai | mistral | together | openrouter | qwen | zhipu | custom Dimensions must match the model (ollama nomic-embed-text = 768, openai text-embedding-3-small = 1536). Empty tables are resized automatically at startup; tables that already hold embeddings are never touched.
# EMBEDDING_PROVIDER=gemini
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
# OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
Ollama's default context window is 4096 tokens and it silently cuts off longer prompts. The bundled ollama service uses 8192 (change it with OLLAMA_CONTEXT_LENGTH below; more context needs more RAM, and Indian-language text uses more tokens per character). If you run your own Ollama on the host, set OLLAMA_CONTEXT_LENGTH=8192 in that Ollama's environment and restart it.
# OLLAMA_CONTEXT_LENGTH=8192
GEMINI_CHAT_MODEL=gemini-3.5-flash
Knowledge Graph (Neo4j) — optional, degrades gracefully if unset
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
Use a long random value (for example `openssl rand -hex 24`). docker-compose.yml gives the same value to the Neo4j container. Leave blank to keep the graph off.
NEO4J_PASSWORD=
Comma-separated domain-specific terms to boost entity extraction, e.g. DOMAIN_TERMS=API,SDK,RAG
DOMAIN_TERMS=
Language Detection (langdetect) — optional, defaults shown below
DEFAULT_LANGUAGE=en
LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD=0.7
Comma-separated list of language codes to restrict detection to (blank = unrestricted)
LANGUAGE_DETECTION_SUPPORTED_LANGUAGES=
Language model. auto (default) downloads a large model from the internet on first use and falls back to a simpler guess when that fails. lite uses the small model that ships with the package and never downloads anything: set it on installs without internet. full = the large model only.
# LANGUAGE_DETECTION_MODEL=auto
Integrations — Fernet key for encrypting stored connection strings/API keys. Generate one with:
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ADDON_ENCRYPTION_KEY=
DemonRoute (https://demonroute.com) — hosted open-weight models via an OpenAI-compatible API. Prepaid with a hard stop at $0; DemonRoute states that it does not retain prompts (https://demonroute.com/privacy), but it forwards them to the upstream host that serves the model, and that page does not describe the upstream host's retention. Third-party service: do not send sensitive business data through it.
# LLM_PROVIDER=demonroute
# DEMONROUTE_API_KEY=your-demonroute-key
# DEMONROUTE_MODEL=hermes-3-llama-3-1-70b
(any DemonRoute model ID works; see https://demonroute.com/docs)
Cheaper Inference (https://cheaperinference.com) — an OpenAI-compatible gateway to models from several labs. Third-party service: it forwards prompts to the upstream provider that serves the model; we have not reviewed its retention policy.
# LLM_PROVIDER=cheaperinference
# CHEAPERINFERENCE_API_KEY=your-cheaperinference-key
# CHEAPERINFERENCE_MODEL=gpt-5.4-mini
(any Cheaper Inference model ID works; see https://cheaperinference.com/docs)
Provider fallback chain — comma-separated provider names to try, in order, if LLM_PROVIDER fails (rate limit, outage, bad key). Each needs its own API key configured normally (e.g. ANTHROPIC_API_KEY). Optional — leave blank to disable fallback entirely.
LLM_FALLBACK_PROVIDERS=
Generation output length and defaults
MAX_OUTPUT_TOKENS=1024
DEFAULT_TEMPERATURE=0.3
Token/context optimization — retrieved chunks are trimmed (lowest- ranked dropped first) once their combined character count exceeds this budget, before being sent to the LLM. ~4 chars/token is a rough English-text approximation, not an exact tokenizer count. Set to 0 to disable trimming entirely.
MAX_CONTEXT_CHARS=12000
Outbound actions (autonomy gate; nothing sends unless configured)
Webhook targets are NAMES the AI can pick, never raw URLs. https only.
# WEBHOOK_TARGETS=n8n=https://your-n8n.example.com/webhook/abc,crm=https://crm.example.com/hook
# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
Email: recipients must be listed (addresses or @domain). Empty = nothing sends.
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# [email protected]
# SMTP_PASSWORD=app-password
# [email protected]
# [email protected],@yourcompany.com
HubSpot CRM record updates: let the AI update properties of EXISTING records (contacts, companies, deals, ...) in your HubSpot account. Take a Private App access token from your HubSpot account (Settings > Integrations > Private Apps, scope crm.objects.*.write). All three values are required; with any of them unset or empty the AI is never offered the tool and nothing is ever written. The object types and the property names it may touch are YOUR allowlists - default empty = deny everything; a record id that does not exist is an error, never a create. Update only, one existing record at a time.
# HUBSPOT_ACCESS_TOKEN=your-hubspot-private-app-token
# HUBSPOT_CRM_UPDATE_OBJECTS=contacts,companies
# HUBSPOT_CRM_UPDATE_PROPERTIES=firstname,lastname,email
Google Calendar: let the AI create events on your calendar (Google Calendar events.insert). Bring your own OAuth client, like the Gmail connector: register a client in your own Google Cloud project with the calendar.events scope and take the refresh token once (e.g. via Google's OAuth Playground). All four values are required; with any of them unset the AI is never offered the tool and nothing is scheduled. Attendees must be on EMAIL_ALLOWED_RECIPIENTS - one address not on the list refuses the whole event. Google emails an invitation / event notification to every attendee (sendUpdates=all). An event with no Attendees: line still schedules on the configured calendar and invites nobody. Start/End are RFC 3339 with a UTC offset, e.g. 2026-03-04T14:00:00+00:00.
# [email protected]
# GOOGLE_CALENDAR_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CALENDAR_CLIENT_SECRET=your-client-secret
# GOOGLE_CALENDAR_REFRESH_TOKEN=your-refresh-token
Sensitive-domain roles created at runtime (PATCH /employees/{role})
A runtime role whose name, display name or skill tags contain a marker word (legal, medical, tax, immigration, insurance, compliance, ...) is treated as sensitive: forced semi/off autonomy, reasoning mode and the grounding check. Built-in sensitive roles can never be exempted.
# SENSITIVE_ROLES_EXTRA=my_custom_role,another_role
# SENSITIVE_ROLES_REVIEWED_SAFE=tax_reminder_bot
Token budgets (all off by default; 0 or unset = unlimited; UTC days/months)
Every LLM call is recorded in the llm_usage table; providers that report no token counts (e.g. Ollama) are ESTIMATED at ~4 characters per token. At a cap, answers return a short "usage limit reached" message without calling the provider.
# BUDGET_DAILY_TOKENS=200000
# BUDGET_MONTHLY_TOKENS=3000000
# BUDGET_ROLE_DAILY_TOKENS=50000
# BUDGET_ROLE_MONTHLY_TOKENS=800000
# BUDGET_ROLE_DAILY_OVERRIDES=support=100000,legal_intake=20000
# BUDGET_ROLE_MONTHLY_OVERRIDES=
# USAGE_LEDGER=off
Docker Compose security defaults
Postgres password for the db, app, voice and worker containers. It only applies when the database volume is first created; to change an existing database also run ALTER USER ragleap WITH PASSWORD '...'. Use letters and digits only (it goes into a URL).
# POSTGRES_PASSWORD=
The API is published on 127.0.0.1 by default. Use 0.0.0.0 only behind a firewall or reverse proxy that adds authentication: RAGLEAP_API_KEY is its only protection (no lockout or rate limiting yet).
# APP_BIND=127.0.0.1
Host ports (the number on your computer, not inside Docker). Defaults are shown. The installer picks the next free port by itself when a default is already used on your computer.
# APP_PORT=8000
# DB_PORT=5433
# VOICE_PORT=8766
# NEO4J_HTTP_PORT=7475
# NEO4J_BOLT_PORT=7688
# REDIS_PORT=6380
Failed-login throttling (on by default)
After AUTH_MAX_FAILURES wrong API keys from one client within AUTH_WINDOW_SECONDS, that client is refused for AUTH_LOCKOUT_SECONDS (even with the right key). Requests with no key are not counted. In memory, per process. Behind a reverse proxy list its address in TRUSTED_PROXIES (IPs or CIDRs) so the real client address from X-Forwarded-For is used; without it every user behind the proxy shares one counter.
# AUTH_THROTTLE=off
# AUTH_MAX_FAILURES=10
# AUTH_WINDOW_SECONDS=300
# AUTH_LOCKOUT_SECONDS=900
# TRUSTED_PROXIES=
Single sign-on addresses (/auth/login, /auth/callback): at most this many requests per client and minute, then 429 with Retry-After. The same client rule as above applies; AUTH_THROTTLE=off switches it off too.
# AUTH_SSO_MAX_PER_MINUTE=30
Switch off the shared key (off by default)
Once an owner has a personal key (POST /users, then POST /users/{id}/keys), set this to refuse RAGLEAP_API_KEY. It only takes effect while an active owner with a live personal key exists, so you cannot lock yourself out.
# SHARED_KEY_DISABLED=true
Request metrics (off by default)
Set METRICS_ENABLED=true below to serve Prometheus text at GET /metrics (an admin key is needed). Counts are per process.
# METRICS_ENABLED=true
Voice channel security (required: without a token the voice server refuses every call)
A long random value (the installer makes one). Twilio's <Stream> must point at wss://your-domain.com:8765/<this value>.
VOICE_WS_TOKEN=
# VOICE_MAX_CALLS=10
# VOICE_MAX_CALL_MINUTES=30
Single sign-on with OpenID Connect (off unless the first four are all set; see docs)
# OIDC_ISSUER=https://idp.example.com/realms/main
# OIDC_CLIENT_ID=ragleap
# OIDC_CLIENT_SECRET=
# OIDC_REDIRECT_URL=https://ragleap.example.com/auth/callback
# OIDC_REQUIRE_MFA=true
# OIDC_REQUIRE_EMAIL_VERIFIED=true
# SSO_SESSION_HOURS=8
# SSO_IDLE_MINUTES=30
Webhook and approval hardening
Telegram: set a secret and register the SAME value as secret_token when calling setWebhook. Without it, webhook requests are now rejected (403).
# TELEGRAM_WEBHOOK_SECRET=
WhatsApp (Twilio): requests without a valid X-Twilio-Signature are rejected (needs TWILIO_AUTH_TOKEN). Local testing only - accept unsigned webhook requests (logs a warning each time):
# TELEGRAM_ALLOW_UNSIGNED=true
# WHATSAPP_ALLOW_UNSIGNED=true
WhatsApp (Meta): WHATSAPP_PROVIDER=meta sends and receives via Meta's WhatsApp Cloud API. META_ACCESS_TOKEN and META_PHONE_NUMBER_ID come from the Meta developer portal (WhatsApp > API Setup), META_VERIFY_TOKEN is any string you also enter as the webhook verify token there, and META_APP_SECRET is the app secret used to check each webhook request's X-Hub-Signature-256 (requests without a valid signature are rejected, 403).
# WHATSAPP_PROVIDER=meta
# META_ACCESS_TOKEN=
# META_PHONE_NUMBER_ID=
# META_VERIFY_TOKEN=
# META_APP_SECRET=
YES/NO approvals are accepted ONLY from the configured owner: the sender must match approval_channel + approval_target set via POST /autonomy.
Optional API-key auth for core/api.py
Unset by default: the API has NO authentication (fine for 127.0.0.1-only access, dangerous if this port is ever reachable beyond localhost). When set, every endpoint except /health and /webhook/* (which verify platform signatures themselves) requires header: X-API-Key: <this value>
# RAGLEAP_API_KEY=
Treat answers built from your documents as untrusted content (default on). When on, an action that follows such an answer needs owner approval even in full autonomy mode, because an ingested document (an email attachment, a synced folder) can carry hidden instructions. Set to false only if you control every document you ingest.
# TAINT_RETRIEVED_DOCUMENTS=true
How long to keep the audit trail, in days. Empty or 0 keeps everything (the default); otherwise at least 7. Deleting history removes evidence: ship the AUDIT log lines to your own log store first, and see docs/audit-retention.md. Finished agent runs only; a run that is running or waiting for approval is never deleted.
# AUDIT_RETENTION_DAYS= # who changed what (audit_events)
# ACTION_LOG_RETENTION_DAYS= # what agents did and who approved it (autonomy_log)
# AGENT_RUN_RETENTION_DAYS= # finished agent runs and their steps (agent_runs)
Put the request id (the X-Request-ID of the call) in every app log line, like "INFO:core.api:[3f9c...] message". The AUDIT lines always carry it. Off by default so the log format stays as it was. See docs/audit-log-lines.md.
# LOG_REQUEST_ID=false