Configuration

NeuralCleave is configured with a single TOML file at ~/.neuralcleave/config.toml. All string values support ENV:VAR_NAME substitution to read secrets from the environment at runtime.

Config file path

The default path is ~/.neuralcleave/config.toml. Override with the environment variable:

bash

NEURALCLEAVE_CONFIG=/path/to/config.toml neuralcleave start

Generate a fresh config with guided setup:

bash

neuralcleave init          # interactive wizard
neuralcleave init -y       # non-interactive, sane defaults

ENV: secret resolution

Any string value in config.toml can reference an environment variable using the ENV: prefix. Resolution happens at gateway startup, not at config parse time:

toml

[models]
anthropic_api_key = "ENV:ANTHROPIC_API_KEY"  # reads $ANTHROPIC_API_KEY
openai_api_key    = "ENV:OPENAI_API_KEY"

💡

Use ENV: references for all secrets. Never commit a config.toml with plaintext API keys.

Full example

toml

# ~/.neuralcleave/config.toml

[agent]
name        = "NeuralCleave"
description = "My personal AI assistant"

[gateway]
host        = "127.0.0.1"
port        = 7432
api_key     = ""             # set to a non-empty string to require X-API-Key
log_level   = "INFO"

[models]
primary_provider     = "anthropic"
primary_model        = "claude-sonnet-4-6"
anthropic_api_key    = "ENV:ANTHROPIC_API_KEY"
openai_api_key       = "ENV:OPENAI_API_KEY"
gemini_api_key       = "ENV:GEMINI_API_KEY"
deepseek_api_key     = "ENV:DEEPSEEK_API_KEY"
ollama_url           = "http://localhost:11434"
ollama_model         = "llama3.2"
extended_thinking    = false
thinking_budget_tokens = 8000
forced_provider      = ""   # override all routing; accepts aliases

[memory]
redis_url            = "redis://localhost:6379/0"
session_ttl_seconds  = 3600
rolling_window_size  = 50
qdrant_url           = "http://localhost:6333"
qdrant_collection    = "neuralcleave_memory"
vector_top_k         = 5
vector_min_score     = 0.60
archive_after_hours  = 24
archive_cron         = "0 3 * * *"

[voice]
enabled              = false
stt_model            = "base"       # tiny | base | small | medium | large-v3
stt_device           = "cpu"        # cpu | cuda
tts_provider         = "kokoro"     # elevenlabs | kokoro | pyttsx3
elevenlabs_api_key   = "ENV:ELEVENLABS_API_KEY"
elevenlabs_voice_id  = ""
wake_word_model      = "hey_jarvis" # or path to .tflite
wake_word_enabled    = false

[scheduler]
enabled = true

[channels.telegram]
bot_token = "ENV:TELEGRAM_BOT_TOKEN"

[channels.discord]
bot_token = "ENV:DISCORD_BOT_TOKEN"

Gateway section

gateway.host string default: "127.0.0.1"

Bind address for the FastAPI gateway. Set to "0.0.0.0" to expose on all interfaces (e.g. for Docker deployments).

gateway.port integer default: 7432

Port the gateway listens on.

gateway.api_key string default: ""

When non-empty, all /api/* requests must include an X-API-Key header matching this value. /health and /ws/* are always exempt.

gateway.log_level string default: "INFO"

Logging verbosity: DEBUG, INFO, WARNING, ERROR.

Models section

models.primary_provider string default: "anthropic"

Default provider for general task type. Accepts any provider name or alias (see LLM Providers).

models.primary_model string default: "claude-sonnet-4-6"

Model identifier for the primary provider.

models.forced_provider string default: ""

When set, overrides task-based routing — every request goes to this provider. Accepts aliases: "kimi", "baidu", "bytedance", etc.

models.extended_thinking bool default: false

Enable Anthropic extended thinking. Forces temperature=1.0. Silently ignored for non-Anthropic providers.

Memory section

memory.redis_url string default: ""

Redis connection URL. Omit to use in-process dict fallback (non-persistent).

memory.session_ttl_seconds integer default: 3600

Redis key TTL for session data. Sessions idle longer than this are evicted from Redis.

memory.qdrant_url string default: ""

Qdrant server URL. Omit to disable semantic memory.

Voice section

voice.stt_model string default: "base"

Whisper model size: tiny, base, small, medium, large-v3. Larger = more accurate, slower to load.

voice.tts_provider string default: "kokoro"

TTS engine: elevenlabs (cloud, highest quality), kokoro (local, zero cost), pyttsx3 (system). Falls back in this order if the preferred provider is unavailable.

voice.wake_word_enabled bool default: false

Enable OpenWakeWord wake-word detection. When active, the microphone listens continuously and triggers on the configured wake word.

Scheduler section

scheduler.enabled bool default: true

Enable the HeartbeatScheduler. When false, all scheduled tasks are skipped.

Scheduled tasks are registered in code (plugins or the gateway itself), not in config. See REST API for the scheduler REST endpoints.