Configuration

Environment variables and config files that drive the stack. ./jarvis up copies .env.example to .env (gitignored) on first run — the values below are all dev-only defaults, never real secrets.

Required keys

tools/checks/env_contract.py enforces which keys .env.example must define for a zero-credential first run: COMPOSE_PROJECT_NAME, POCKETBASE_HOST_PORT, POCKETBASE_URL, SUPERUSER_EMAIL, SUPERUSER_PASSWORD, DEV_USER_EMAIL, DEV_USER_PASSWORD, LLM_PROVIDER. It also enforces that JARVIS_IMAP_MAIN_USER and JARVIS_IMAP_MAIN_PASSWORD stay documented (as commented-out lines) even though they're optional.

.env.example

Every variable .env.example defines, in file order.

Var	Default	Purpose
COMPOSE_PROJECT_NAME	jarvis	Compose project name — keeps this stack's containers/volumes separate from other stacks on the same host.
POCKETBASE_HOST_PORT	8091	Host port PocketBase is published on (127.0.0.1 only).
POCKETBASE_URL	http://pocketbase:8090	PocketBase URL as seen inside the compose network (service name) — used by the bootstrap/agent/cli containers.
SUPERUSER_EMAIL	dev@jarvis.local	PocketBase superuser email, upserted on first run (dev-only).
SUPERUSER_PASSWORD	devpassword123	PocketBase superuser password (dev-only).
DEV_USER_EMAIL	user@jarvis.local	The seeded app-user account's email.
DEV_USER_PASSWORD	userpassword123	The seeded app-user account's password.
LLM_PROVIDER	stub	LLM backend: stub runs fully offline with canned responses; set to deepseek (and supply DEEPSEEK_API_KEY) for the real provider.
DEEPSEEK_API_KEY	(commented out)	DeepSeek API key — required when LLM_PROVIDER=deepseek.
JARVIS_IMAP_MAIN_USER	(commented out)	Owner-supplied IMAP username for the live email capture connector. Optional — capture is disabled unless a cap_connectors row enables it.
JARVIS_IMAP_MAIN_PASSWORD	(commented out)	Owner-supplied IMAP app password, paired with JARVIS_IMAP_MAIN_USER. Never commit a real value.
JARVIS_VECTOR_DB	(commented out)	Conversation module: sidecar vector-store path (falls back to <JARVIS_PB_DATA or pb_data>/vectors.db).
JARVIS_EMBED_MODEL	(commented out)	Conversation module: embedding model id (falls back to a multilingual MiniLM model).
JARVIS_INDEX_EXCLUDE	(commented out)	Conversation module: extra :-separated exclude globs when indexing the vault.

Runtime / host-supplied

Vars the running system reads but that aren't in .env.example — supplied by Compose service environment: blocks, a LaunchAgent's EnvironmentVariables, or set by hand for a one-off run.

Var	Default	Purpose
DEEPSEEK_BASE_URL	https://api.deepseek.com	DeepSeek API base URL, overridable for testing.
LLM_MODEL	deepseek-chat	DeepSeek model id.
AGENT_DRY_RUN	unset (falsy)	Any value other than empty/0 puts the agent runtime in dry-run mode.
JARVIS_OWNER_EMAIL	""	Comma-separated owner addresses, used to distinguish the owner's own messages/handles across connectors.
JARVIS_VAULT_DIR	unset (required where used)	Obsidian vault root — shared by the capture pipeline and the conversation module's indexer/resolver.
JARVIS_DISCORD_TOKEN	unset	Discord bot token for the live Discord capture connector (declared as a capture module secret).
JARVIS_GRAFANA_URL	unset (required)	Base URL of the Grafana instance the homelab agent reads from.
JARVIS_GRAFANA_TOKEN	unset (required)	Bearer token for the Grafana/Prometheus API.
JARVIS_GRAFANA_DS_UID	""	Datasource UID used to fetch per-alert PromQL evidence; without it, alerts are reported without evidence.
JARVIS_PB_DATA	/vault (scheduler) / pb_data (fallback)	Base dir the conversation module derives its default vector-store path from.
JARVIS_EMBED_FAKE	unset	Set to 1 to use a fake (non-downloading) embedding provider — used in tests/CI.
JARVIS_CHAT_POLL_SECS	2.0	Chat-tab worker's poll interval between checking for pending turns.
JARVIS_CHAT_CONTEXT_CHARS	4000	Chat-tab worker's character cap on context assembled per turn.
CAPTURE_POLL_LIMIT	200	Max items the capture poll fetches per connector per run.

Flutter dart-defines

Resolved by core/lib/config/core_config.dart via --dart-define, with safe fallback defaults baked in.

Dart-define	Default	Purpose
JARVIS_BACKEND_URL	"" (empty)	Pre-fills the first-run backend-URL field; empty means "ask the owner".
JARVIS_USERS_COLLECTION	users	Backend collection name the app resolves the logical users collection to.
JARVIS_DEMO_ITEMS_COLLECTION	demo_items	Backend collection name the app resolves the logical demo_items collection to.
JARVIS_LLM_PROVIDER	deepseek	LLM provider label the app displays/assumes for its own UI.