Documentation Index
Fetch the complete documentation index at: https://docs.feral.sh/llms.txt
Use this file to discover all available pages before exploring further.
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. |
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 |
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_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 |
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.
