Environment Variables

Overview

Environment variables are the highest-priority configuration source — they override everything in settings.json. Set them in your shell profile, .env file, or container environment.

LLM Provider Keys

Variable	Default	Description
`ANTHROPIC_API_KEY`	—	Anthropic Claude API key
`OPENAI_API_KEY`	—	OpenAI API key (GPT-4, Realtime)
`OPENROUTER_API_KEY`	—	OpenRouter multi-model gateway key
`GOOGLE_API_KEY`	—	Google Gemini API key
`OLLAMA_HOST`	`http://localhost:11434`	Ollama server URL (local models)
`FERAL_LLM_PROVIDER`	`ollama`	Default provider: `anthropic`, `openai`, `openrouter`, `gemini`, `ollama`
`FERAL_LLM_MODEL`	`llama3`	Default model identifier
`FERAL_LLM_TEMPERATURE`	`0.7`	Default sampling temperature
`FERAL_LLM_MAX_TOKENS`	`4096`	Maximum tokens per response

LLM failover & spend controls

These control the resilience layer in agents/llm_provider.py. They are optional — leaving every value at its default keeps the historical primary-then-fallback ordering.

Variable	Default	Description
`FERAL_LLM_COOLDOWN_STATE_PATH`	`<FERAL_HOME>/llm_provider_cooldowns.json`	Override path for the persisted provider cooldown / circuit state. Survives process restarts so a 24h `auth_permanent` lock-out is not reset by a redeploy.
`FERAL_LLM_DAILY_BUDGET_USD`	`0`	Daily spend ceiling, in USD. `0` disables budget-aware routing. Overrides `llm.daily_budget_usd` in `settings.json`.
`FERAL_LLM_DAILY_SPEND_USD`	`0`	Spend already accounted for today, in USD. Used to compute remaining headroom. Overrides `llm.daily_spend_usd`.
`FERAL_LLM_BUDGET_TIGHT_RATIO`	`0.25`	Fraction of remaining budget below which the failover loop reorders affordable candidates by cheapest-first instead of configured priority. Clamped to `[0.0, 1.0]`. Overrides `llm.budget_tight_ratio`.

When budget routing is enabled, GET /api/llm/health (the v2 “Fallbacks” card source) includes a budget block with daily_budget_usd, daily_spend_usd, remaining_usd, headroom_ratio, tight_ratio, and per-candidate cost estimates from the most recent dispatch.

Core Settings

Variable	Default	Description
`FERAL_HOME`	`~/.feral`	Root directory for all FERAL data (config, memory, logs)
`FERAL_BRAIN_PORT`	`9090`	Brain WebSocket and API port
`FERAL_HOST`	`127.0.0.1`	Primary bind host (set `0.0.0.0` for LAN reachability)
`FERAL_BIND_HOST`	—	Legacy alias for bind host
`FERAL_BRAIN_HOST`	—	Backward-compatible host override
`FERAL_PUBLIC_BASE_URL`	—	Public base URL used for remote pairing URL generation
`FERAL_LOG_LEVEL`	`info`	Logging level: `debug`, `info`, `warn`, `error`

Update Checks

Variable	Default	Description
`FERAL_UPDATE_CHECK`	`false`	Let the brain ask PyPI whether a newer `feral-ai` exists. Off by default: nothing contacts the network unless you turn this on. Also settable as `updates.check_pypi` in `~/.feral/settings.json`
`FERAL_UPDATE_CHECK_TTL_HOURS`	`24`	How long a successful answer is cached (`updates.ttl_hours`). Failures are re-tried after an hour
`FERAL_PYPI_JSON_URL`	`https://pypi.org/pypi/feral-ai/json`	Point the check at an internal mirror instead

With the check on, the brain asks once per TTL on a background task and never on a request path; GET /api/dashboard and feral doctor read the cached answer only. An unreachable index reports unknown, never an error. feral update asks on demand whatever this is set to, because running the command is the request.

Autonomy & Security

Variable	Default	Description
`FERAL_AUTONOMY`	`hybrid`	`strict`, `hybrid`, or `loose`
`FERAL_SANDBOX_ENABLED`	`true`	Enable WASM sandbox for skill execution
`FERAL_APPROVAL_TIMEOUT`	`30`	Seconds to wait for user approval before timing out
`FERAL_VAULT_KEY`	—	Override vault encryption key (not recommended)

Docker sandbox hardening

These tune the runtime flags applied to every container started by security/docker_sandbox.py. Defaults are the safe values — only override when you have a concrete reason.

Variable	Default	Description
`FERAL_SANDBOX_PIDS_LIMIT`	`128`	Max processes inside the container (`--pids-limit`). Floor of `16` is enforced.
`FERAL_SANDBOX_CAP_DROP`	`ALL`	Linux capabilities to drop (`--cap-drop`). Set to empty string to skip the flag entirely (not recommended).
`FERAL_SANDBOX_NO_NEW_PRIVILEGES`	`true`	Apply `--security-opt no-new-privileges`. Accepts `1/0/true/false/yes/no/on/off`.
`FERAL_SANDBOX_SECCOMP_PROFILE`	—	Path to a custom seccomp JSON profile applied via `--security-opt seccomp=…`. The literal value `unconfined` is rejected with a warning.
`FERAL_SANDBOX_PREFER_REGISTRY`	`false`	When `true`, resolve the sandbox image tag from the published registry first instead of the locally-built tag.

Voice

Variable	Default	Description
`FERAL_VOICE_ENABLED`	`true`	Enable voice pipeline
`FERAL_VOICE_PROVIDER`	`openai_realtime`	`openai_realtime`, `gemini_live`, `whisper_local`
`FERAL_WAKE_WORD`	`hey feral`	Wake word trigger phrase
`FERAL_VOICE_LANGUAGE`	`en`	Language code for speech recognition

Vision & Perception

Variable	Default	Description
`FERAL_VISION_ENABLED`	`true`	Enable vision pipeline (screen + glasses)
`FERAL_SCREEN_CAPTURE`	`true`	Allow screen capture for computer-use features
`FERAL_VISION_MODEL`	`local`	Vision model: `local` (YOLO), `openai`, `gemini`
`FERAL_VISION_INTERVAL`	`2`	Seconds between vision frame analysis

Audio

Variable	Default	Description
`FERAL_AUDIO_INPUT`	`default`	Audio input device name or `default`
`FERAL_AUDIO_OUTPUT`	`default`	Audio output device name or `default`
`FERAL_AUDIO_SAMPLE_RATE`	`16000`	Audio sample rate in Hz

Channels

Variable	Default	Description
`FERAL_TELEGRAM_BOT_TOKEN`	—	Telegram bot token from BotFather
`FERAL_SLACK_BOT_TOKEN`	—	Slack bot user OAuth token (`xoxb-`)
`FERAL_SLACK_APP_TOKEN`	—	Slack app-level token for Socket Mode (`xapp-`)
`FERAL_DISCORD_BOT_TOKEN`	—	Discord bot token
`FERAL_FCM_SERVICE_ACCOUNT_PATH`	—	Path to Firebase service account JSON
`FERAL_APNS_KEY_PATH`	—	Path to APNs `.p8` key file
`FERAL_APNS_KEY_ID`	—	APNs key ID
`FERAL_APNS_TEAM_ID`	—	Apple Developer Team ID
`FERAL_APNS_BUNDLE_ID`	`com.feral.app`	iOS app bundle identifier
`FERAL_APNS_ENVIRONMENT`	`production`	`sandbox` or `production`

Hardware

Variable	Default	Description
`FERAL_BLE_ENABLED`	`true`	Enable Bluetooth device scanning
`FERAL_HUP_PORT`	`9091`	Hardware Unified Protocol WebSocket port
`FERAL_GENERIC_HARDWARE_SKILLS`	`1`	When enabled (default), any self-describing `DeviceManifest` auto-generates LLM tools via `GenericHardwareSkill`. Set to `0` to fall back to hand-written skill manifests only (e.g. legacy `cutebot.json`).
`FERAL_CUTEBOT_PATH`	—	Path to the `cuteferalbot` repo root when CuteBot is not installed as a package. Used by brain-local discovery (`hardware/discovery.py`).
`FERAL_HA_URL`	—	Home Assistant URL (e.g., `http://192.168.1.50:8123`)
`FERAL_HA_TOKEN`	—	Home Assistant long-lived access token

Memory

Variable	Default	Description
`FERAL_MEMORY_BACKEND`	`sqlite`	Memory storage: `sqlite`, `postgres`
`FERAL_MEMORY_PATH`	`~/.feral/memory.db`	Path to the memory database file
`FERAL_VECTOR_STORE`	`chroma`	Vector store for semantic search: `chroma`, `qdrant`
`FERAL_MEMORY_SYNC`	`false`	Enable P2P memory sync across devices
`FERAL_EMBED_FALLBACK`	`hash`	Embedding fallback when primary provider degrades (`hash`, `local`, `skip`)

Pairing & Access

Variable	Default	Description
`FERAL_HOST`	`127.0.0.1`	LAN pairing needs `0.0.0.0` in many setups
`FERAL_PUBLIC_BASE_URL`	—	Optional explicit remote pair URL base

Integrations

Variable	Default	Description
`FERAL_GOOGLE_CREDENTIALS`	—	Path to Google OAuth credentials JSON (Calendar, Gmail)
`FERAL_SPOTIFY_CLIENT_ID`	—	Spotify app client ID
`FERAL_SPOTIFY_CLIENT_SECRET`	—	Spotify app client secret
`FERAL_NOTION_TOKEN`	—	Notion integration token
`FERAL_WHOOP_CLIENT_ID`	—	Whoop API client ID
`FERAL_WHOOP_CLIENT_SECRET`	—	Whoop API client secret
`FERAL_OURA_PAT`	—	Oura Ring personal access token

Coding Harness

Each of these also has a settings.json mirror under the coding section (FERAL_READ_BEFORE_EDIT mirrors coding.read_before_edit, and so on), so a choice can be persisted instead of re-exported on every launch. The environment variable stays the higher-priority source: set it and it wins over settings.json.

Variable	Default	Description
`FERAL_READ_BEFORE_EDIT`	`warn`	`off`, `warn`, or `enforce`. Whether editing a file the session has not read is refused, warned about, or ignored
`FERAL_TOOL_CALL_CONTEXT`	`on`	Intended as an off switch for the per-call tool context. Currently inert: the only reader is `skills/call_context.py::context_enabled()`, which nothing calls, so setting it to `off` changes no behaviour
`FERAL_EDIT_MAX_CONTENT_LINES`	`4000`	Above this file size only the exact edit matcher runs
`FERAL_EDIT_MAX_NEEDLE_LINES`	`400`	Above this needle size only the exact edit matcher runs
`FERAL_CHECKPOINT_DIR`	`$FERAL_HOME/checkpoints`	Overrides the checkpoint store location outright
`FERAL_CHECKPOINT_RETENTION_DAYS`	`14`	Days a checkpoint is kept before pruning
`FERAL_CHECKPOINT_MAX_BLOB_BYTES`	`8388608`	8 MiB cap on a single checkpointed file
`FERAL_POST_EDIT_DIAGNOSTICS`	`on`	`off` skips the diagnostics pass after an edit
`FERAL_DIAGNOSTICS_TIMEOUT`	`5`	Seconds allowed for that diagnostics pass (floored at 0.5)
`FERAL_TURN_IDLE_SECONDS`	`180`	Seconds a turn may sit idle before the tool loop gives up

Feature Flags

Variable	Default	Description
`FERAL_PROACTIVE_ENABLED`	`true`	Enable proactive intelligence engine
`FERAL_GENUI_ENABLED`	`true`	Enable server-driven UI generation
`FERAL_DIGITAL_TWIN`	`true`	Enable digital twin reasoning
`FERAL_LOCATION_TRACKING`	`false`	Enable GPS geofencing triggers

Earlier versions of these docs listed a FERAL_COMPUTER_USE flag — that variable was never wired into the code. To gate computer-use, change autonomy mode in the WebUI Settings → Autonomy picker (writes security.autonomy_mode in ~/.feral/settings.json); strict requires approval for every action, hybrid (default) requires approval for destructive / dangerous-tier actions only, loose auto-runs everything.

Set feature flags to false to disable subsystems you don’t need — this reduces memory usage and startup time.

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Environment Variables

Overview

LLM Provider Keys

LLM failover & spend controls

Core Settings

Update Checks

Autonomy & Security

Docker sandbox hardening

Voice

Vision & Perception

Audio

Channels

Hardware

Memory

Pairing & Access

Integrations

Coding Harness

Feature Flags

​Overview

​LLM Provider Keys

​LLM failover & spend controls

​Core Settings

​Update Checks

​Autonomy & Security

​Docker sandbox hardening

​Voice

​Vision & Perception

​Audio

​Channels

​Hardware

​Memory

​Pairing & Access

​Integrations

​Coding Harness

​Feature Flags

Overview

LLM Provider Keys

LLM failover & spend controls

Core Settings

Update Checks

Autonomy & Security

Docker sandbox hardening

Voice

Vision & Perception

Audio

Channels

Hardware

Memory

Pairing & Access

Integrations

Coding Harness

Feature Flags