Configuration

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:

User config (lowest priority)

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

Project config

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

Local config

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

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"
  },
  "security": {
    "autonomy_mode": "hybrid"
  },
  "coding": {
    "read_before_edit": "warn",
    "tool_call_context": "on",
    "post_edit_diagnostics": "on",
    "checkpoint_retention_days": 14,
    "turn_idle_seconds": 180
  },
  "network": {
    "port": 9090,
    "bind_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-...

export OPENAI_API_KEY=sk-...

export OPENROUTER_API_KEY=sk-or-...

# No key needed — Ollama is auto-detected on localhost:11434

Key Settings Reference

Setting Path	Type	Default	Description
`llm.provider`	string	`"ollama"`	LLM backend: `anthropic`, `openai`, `openrouter`, `ollama`, `gemini`
`llm.model`	string	`"llama3"`	Model identifier for the chosen provider
`security.autonomy_mode`	string	`"hybrid"`	`strict`, `hybrid`, or `loose`. See Autonomy
`voice.enabled`	bool	`true`	Enable voice pipeline
`voice.wake_word`	string	`"hey feral"`	Trigger phrase for hands-free activation
`network.port`	int	`9090`	Brain WebSocket/API port. `FERAL_PORT` and `FERAL_BRAIN_PORT` both override it
`network.bind_host`	string	`"127.0.0.1"`	Bind host (`0.0.0.0` if you need LAN phone reachability). `FERAL_HOST` and `FERAL_BIND_HOST` both override it
`access.pairing_mode`	string	`"localhost"`	`localhost`, `local`, or `remote`
`memory.backend`	string	`"sqlite_vec"`	Storage backend for episodic memory
`hardware.ble_enabled`	bool	`true`	Enable Bluetooth device scanning

The `coding` Section

Knobs for the coding harness. Each one shipped as an environment variable only, so it was configurable per process but not persistable: an operator who wanted read-before-edit enforced had to re-export the variable on every launch. They are mirrored into settings.json so the choice survives a restart.

Setting Path	Type	Default	Description
`coding.read_before_edit`	string	`"warn"`	`off`, `warn`, or `enforce`. Whether writing a file this session never read is ignored, warned about, or refused
`coding.tool_call_context`	string	`"on"`	Currently inert. Intended as an off switch for the per-call session/turn context. `call_context.context_enabled()` reads it and nothing calls that function, so setting it to `off` changes no behaviour today. The key passes the reader gate on the env-var read inside that unused function; see the known limit
`coding.edit_max_content_lines`	int	`4000`	Above this file size only the exact edit matcher runs
`coding.edit_max_needle_lines`	int	`400`	Above this `old_text` size only the exact edit matcher runs
`coding.checkpoint_dir`	string	`""`	Empty means `$FERAL_HOME/checkpoints`. Any non-empty value overrides that outright
`coding.checkpoint_retention_days`	int	`14`	Days a checkpoint row is kept before pruning. Blobs no surviving row references are deleted with it
`coding.checkpoint_max_blob_bytes`	int	`8388608`	8 MiB. A larger file is recorded but not blobbed, and reverts report it as unrecoverable rather than pretending
`coding.post_edit_diagnostics`	string	`"on"`	`off` skips the post-write checker pass
`coding.diagnostics_timeout`	int	`5`	Seconds allowed for that pass. Floored at 0.5
`coding.turn_idle_seconds`	int	`180`	Seconds a turn may sit idle before the tool loop gives up

Precedence here is env-first, unlike the general rule above, and it is deliberate. Each of these is read from the process environment by its subsystem and from nowhere else. The environment variable is merged into the coding section on load and then re-emitted verbatim by export_as_env, so a shell that exports FERAL_READ_BEFORE_EDIT=enforce still beats settings.json. The defaults above are copied from each reader’s own default, so an install that never touches this section behaves exactly as it did before the section existed.

The environment variable names are in the Environment reference.

Example: Minimal Cloud Config

settings.json

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "security": { "autonomy_mode": "strict" }
}

Example: Fully Local Config

settings.json

{
  "llm": {
    "provider": "ollama",
    "model": "llama3:70b"
  },
  "voice": {
    "provider": "whisper_local"
  },
  "security": { "autonomy_mode": "loose" }
}

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Configuration

Config File Location

Configuration Hierarchy

Settings File Format

Credentials Vault

Managing credentials

Key Settings Reference

The `coding` Section

Example: Minimal Cloud Config

Example: Fully Local Config

​Config File Location

​Configuration Hierarchy

​Settings File Format

​Credentials Vault

​Managing credentials

​Key Settings Reference

​The coding Section

​Example: Minimal Cloud Config

​Example: Fully Local Config

Config File Location

Configuration Hierarchy

Settings File Format

Credentials Vault

Managing credentials

Key Settings Reference

The `coding` Section

Example: Minimal Cloud Config

Example: Fully Local Config