Skip to main content

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.

​
Config File Location

FERAL reads its primary configuration from a JSON file at: 
~/.feral/settings.json
You can override this path by setting the FERAL_HOME environment variable: 
export FERAL_HOME=/path/to/my/feral
When set, FERAL reads $FERAL_HOME/settings.json instead.

​
Configuration Hierarchy

FERAL merges configuration from four sources, each overriding the previous:
1

User config (lowest priority)

~/.feral/settings.json — your global defaults.
2

Project config

.feral/settings.json in the current working directory — project-specific overrides.
3

Local config

.feral/settings.local.json in the current directory — personal overrides not checked into version control.
4

Environment variables (highest priority)

Any FERAL_* env var overrides the equivalent setting. See the Environment Variables reference.
Add .feral/settings.local.json to your .gitignore to keep personal overrides out of version control.

​
Settings File Format

settings.json
{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "temperature": 0.7,
    "max_tokens": 4096
  },
  "voice": {
    "enabled": true,
    "wake_word": "hey feral",
    "provider": "openai_realtime"
  },
  "autonomy": {
    "mode": "hybrid",
    "safe_categories": ["information", "media", "smart_home"],
    "risky_categories": ["email", "file_delete", "purchase"]
  },
  "ui": {
    "theme": "dark",
    "show_debug": false
  },
  "brain": {
    "port": 9090,
    "host": "127.0.0.1"
  },
  "access": {
    "pairing_mode": "localhost"
  },
  "memory": {
    "backend": "sqlite",
    "vector_store": "chroma",
    "path": "~/.feral/memory.db"
  },
  "hardware": {
    "ble_enabled": true,
    "home_assistant_url": null,
    "hup_port": 9091
  }
}

​
Credentials Vault

Sensitive values (API keys, OAuth tokens) are stored separately in the encrypted BlindVault: 
~/.feral/credentials.enc
The vault is encrypted at rest with ChaCha20-Poly1305 (AEAD). The 32-byte master key lives in your OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) — there is no master password stored on disk; unlocking the vault requires the keychain entry to be present, so the brain decrypts transparently inside your OS account and refuses to start anywhere that entry is missing. At first boot FERAL prints a one-time recovery code (the master key, base32-encoded) you can use to recover the vault if the keychain entry is ever wiped; FERAL has no escrow. The decrypted credentials live only in process memory and the LLM never sees raw values — keys are injected at the HTTP layer at request time.
Never commit credentials.enc to version control. The setup wizard creates it automatically and pip install feral-ai adds ~/.feral/ to your gitignore patterns when you run feral setup.

​
Managing credentials

feral setup                     # interactive wizard — sets keys and encrypts
You can also set credentials via environment variables, which always take precedence over the vault: 
export ANTHROPIC_API_KEY=sk-ant-...

​
Key Settings Reference

Setting PathTypeDefaultDescription
llm.providerstring"ollama"LLM backend: anthropic, openai, openrouter, ollama, gemini
llm.modelstring"llama3"Model identifier for the chosen provider
autonomy.modestring"hybrid"strict, hybrid, or loose
voice.enabledbooltrueEnable voice pipeline
voice.wake_wordstring"hey feral"Trigger phrase for hands-free activation
brain.portint9090Brain WebSocket/API port
brain.hoststring"127.0.0.1"Bind host (0.0.0.0 if you need LAN phone reachability)
access.pairing_modestring"localhost"localhost, local, or remote
ui.themestring"dark"Web dashboard theme (dark or light)
memory.backendstring"sqlite"Storage backend for episodic memory
hardware.ble_enabledbooltrueEnable Bluetooth device scanning

​
Example: Minimal Cloud Config

settings.json
{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "autonomy": { "mode": "strict" }
}

​
Example: Fully Local Config

settings.json
{
  "llm": {
    "provider": "ollama",
    "model": "llama3:70b"
  },
  "voice": {
    "provider": "whisper_local"
  },
  "autonomy": { "mode": "loose" }
}