Skip to content
The world does revolve around you.

Environment variables#

Ostler reads its runtime configuration from a single dotenv file at ~/.ostler/config/.env. Every variable in this reference is overridable by exporting it in the shell before launching the Hub, but the dotenv file is the canonical home.

This page lists user-tunable variables only. Internal flags (test harness toggles, debug switches) are deliberately omitted; they may change without notice.

How variables are loaded#

The installer writes ~/.ostler/config/.env at the end of Phase 3. On each boot the Hub processes source that file, then any variable set in the shell takes precedence:

default in code → ~/.ostler/config/.env → shell environment

The ostler-import CLI also sources this file before running. To pick up a change in the dotenv file, restart the Hub services (or simply re-run the affected command).

See Configuration for the higher-level config file schema.

Identity#

Name Default Purpose Set by user
USER_ID empty Stable user ID. Used as the subject suffix in graph storage and as a partition key across the Hub. Treat as an immutable primary key. Y (installer prompt)
USER_NAME empty Display name used by the assistant and in generated artefacts. Cosmetic; safe to rename. Y (installer prompt)
ASSISTANT_NAME (no default – set during install) Display name for the assistant persona. Y (installer prompt)

Locale#

Name Default Purpose Set by user
TIMEZONE UTC IANA timezone name (Europe/London, Asia/Hong_Kong, etc.). Drives date formatting and calendar windowing. Y
DEFAULT_COUNTRY_CODE 44 Country dialling code used to normalise phone numbers without a + prefix. Y

Storage backends#

Ostler stores knowledge in three local services run as Docker containers: a vector store (semantic search), a graph store (relationships and facts), and a cache. The defaults below assume a single-machine deploy.

Name Default Purpose Set by user
QDRANT_URL http://localhost:6333 Vector store base URL. Override if you run the container on a non-default port. Y (advanced)
OXIGRAPH_URL http://localhost:7878 Graph store base URL. Override if you run the container on a non-default port. Y (advanced)
REDIS_URL redis://localhost:6379 Cache and message-bus URL. Y (advanced)
QDRANT_COLLECTION people Vector store collection name for the People graph. N

Embedding#

Name Default Purpose Set by user
EMBED_OLLAMA_URL http://localhost:11434 Ollama HTTP endpoint used for generating embeddings. Y (advanced)
EMBED_MODEL nomic-embed-text Embedding model name pulled from Ollama. Y (advanced)
EMBED_BATCH_SIZE 50 Batch size for bulk embedding jobs. Tune up for faster import on capable hardware. Y

API server#

These control the local HTTP API documented in the API reference.

Name Default Purpose Set by user
OSTLER_API_BIND 127.0.0.1 Bind address for the API server. Set to 0.0.0.0 to expose on every interface (LAN deploys without Tailscale). Tailscale is the recommended way to reach the Hub remotely. Y (advanced)
MAX_POST_BYTES 1048576 (1 MB) POST body size cap. Requests exceeding this return HTTP 413. Y
HUB_VERSION 0.1.0 Reported in /api/v1/hub/health. Set by the installer; rarely changed. N
HUB_CHECK_TIMEOUT_SECONDS 2.0 Per-dependency timeout for the hub-health endpoint. Y (advanced)
INGEST_DIR ~/.ostler/ingest Landing zone for POST /api/v1/ingest/ios payloads. Y
WIKI_BASE_URL http://localhost:8044 Base URL used when generating wiki links in API responses. Y (advanced)

Ollama#

Name Default Purpose Set by user
OLLAMA_URL http://localhost:11434 Ollama endpoint used by the Hub for chat models (separate from the embedding endpoint, which can point to a different host). Y (advanced)
OLLAMA_HEADLINE_MODEL qwen3:8b Model used for short fact headlines in the wiki compiler. Larger narrative summaries use a separate model. Y

CardDAV (contact sync)#

Set these to enable contact synchronisation from a CardDAV server (iCloud Contacts and most major providers support CardDAV).

Name Default Purpose Set by user
CARDDAV_URL empty CardDAV server URL. Empty disables contact sync. Y
CARDDAV_USERNAME empty CardDAV account username. Y
CARDDAV_PASSWORD empty App-specific password (NEVER your main account password). Stored in ~/.ostler/config/.env only. Y

Encryption#

Name Default Purpose Set by user
OSTLER_DB_KEY unset Database key used to read encrypted local databases. Set by the Hub launchers after passphrase unlock; not normally set by hand. N (managed by Hub)

Onboarding sources#

These tune what data the installer's macOS extraction step pulls in. They are written to ~/.ostler/config/.env during install and read again on ostler-fda re-runs.

Name Default Purpose Set by user
OSTLER_FDA_SOURCES safari_history,safari_bookmarks,apple_notes,calendar,reminders Comma-separated list of macOS sources to extract. Remove an entry to skip that source. Y (installer prompt)
OSTLER_TAKEOUT_PATH empty Absolute path to a Google Takeout .mbox or .zip to register at install time. Y

Networking#

Name Default Purpose Set by user
OSTLER_TAILSCALE_IP empty The Mac's Tailscale IPv4 address. Set by the installer when Tailscale is configured; used by the Ostler iOS app to reach the Hub from outside the home network. Y (installer flow)

Paths#

Name Default Purpose Set by user
OSTLER_HOME ~/.ostler Base directory for Hub data, config, and logs. Y
PWG_HOME ~/.pwg Base directory for processed conversations and the coach observation database. Y (advanced)

Installer#

These are read at install time only. See the CLI reference for installer flags.

Name Default Purpose Set by user
OSTLER_BETA unset Skip the invite-code prompt for friends-and-family testers. Y (beta only)

Diagnostic dashboard (Doctor)#

Name Default Purpose Set by user
DOCTOR_PORT 8089 Port the Ostler Doctor diagnostic dashboard binds to. Y (advanced)
DOCTOR_SUPPORT_EMAIL [email protected] Support email shown in Doctor's UI. Y (white-label deploys)

Power management (MacBook Hub)#

POWER_POLICY is read from ~/.ostler/power.conf, NOT from the shell environment or ~/.ostler/config/.env. Edit that file to change the policy.

Name Default Purpose Set by user
POWER_POLICY normal One of normal, aggressive, eco. Controls how aggressively Docker and Ollama are paused on battery. Y

Variables NOT documented here#

The following categories of variable are deliberately not user-facing:

  • Test harness toggles (anything an end-user should never need)
  • Internal debug flags
  • Repository-pinning overrides used during dev (OSTLER_PIPELINE_REPO, OSTLER_HUB_POWER_REPO) – relevant only for forks and private betas

If you find yourself needing one of these for a real deployment, please raise an issue – it probably belongs on this page.

See also#

  • Configuration – the canonical config file format.
  • API reference – every endpoint that consumes these variables.
  • CLI – installer and management commands.