Skip to main content

​
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"]
  },
  "dashboard": {
    "port": 3000,
    "theme": "dark"
  },
  "brain": {
    "port": 9090,
    "host": "0.0.0.0"
  },
  "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, tokens) are stored separately in an encrypted vault: 
~/.feral/credentials.json
This file is AES-256 encrypted at rest using a key derived from your system keychain. FERAL decrypts it in memory at startup.
Never commit credentials.json to version control. The setup wizard creates it automatically.

​
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
dashboard.portint3000Web dashboard port
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" },
  "dashboard": { "port": 3000 }
}