Configuration

Configuration

Run it: brainless.toml, the profile, the environment and the secrets.

A lite install keeps its settings in one file, brainless.toml, and brainless init writes it for you. My own setup ran for months on environment variables alone, and still does. So the file changes nothing underneath. Each line in it is a default for one of those variables, and a variable set in the shell still wins. Keys live in the OS keychain. .env.example lists every variable and brainless.toml.example every setting.

0. brainless.toml

At the vault root. brainless config show prints the variables it sets.

profile = "lite"

[owner]
name = "Ada"
lang = "tr"

[folders]            # roles, not names: the engine asks for "daily", not "Notlar"
inbox = "Gelen"
daily = "Notlar"
library = "Kütüphane"
thinking = "Düşünce"
sources = ["Kütüphane/_linked/old-vault"]   # linked folders brainless init added

[llm]
provider = "ollama"  # anthropic, openai, grok, gemini, openrouter, openai-compatible,
model = "qwen3:8b"   # claude-cli, codex-cli, gemini-cli, goose

[llm.lanes.compile]  # optional: one lane on its own provider or model
provider = "anthropic"

# with the anthropic provider: a monthly cap, warn and stop ratios, the reset day,
# the house-rules file sent as the system prompt, and the workspace id an
# account-linked key needs (see AI Shed)
# api_budget_usd = 100
# api_budget_warn = 0.8
# api_budget_stop = 0.9
# api_budget_reset_day = 1
# system_prompt_file = "_Agent-Context/LLM-SYSTEM.md"
# anthropic_workspace_id = "wrkspc_..."

[schedule]
enabled = true

[commands]
enable = ["media"]   # full-profile commands shown on lite

A key written here is ignored with a warning. Store keys with brainless config secret set <name>: anthropic_api_key, openai_api_key, xai_api_key, gemini_api_key, openrouter_api_key, or llm_api_key for a generic OpenAI-compatible endpoint. On macOS they go to the login Keychain under the service brainless; on Linux to libsecret when secret-tool is installed, otherwise to ~/.config/brainless/secrets.env with mode 600. Each provider reads only its own key. See Lite.

1. The vault profile

_Agent-Context/PROFILE.md is written by the installer, then edited. owner_name and output_lang shape every prompt; worker_name is the commit suffix an always-on machine signs with; private_segments names folders the compiler must never read.

---
owner_name: Tunca
output_lang: tr
company_area: Work
worker_name: omarchy
owner_full_name: Tunca
private_segments: Official Docs, Security Incidents
---

private_segments is the privacy seam: add any folder name and it is ignored anywhere in the tree, never compiled into .wiki/. See Ownership and Privacy.

Optional keys:

Key	What it does
private_name_parts	Parts of a folder name that make it private wherever they appear, for names that change (an export with a date in it)
personal_markers	Path parts that mark a concept page personal: it is compiled, but chat notifications only count it and it is never exported
backup_dir	Where brainless backup create writes the encrypted archive, a folder sync does not reach
backup_recipient	The age1... public key the archive is sealed to; the private key stays in your password manager

2. Environment

Set in your shell profile, identical on every machine that shares the vault:

export BRAINLESS_VAULT=~/projects/brainless
export BRAINLESS_OUTPUT_LANG=tr
export BRAINLESS_LLM_PROVIDER=claude-cli   # signed-in claude CLI, no API key

Variable	Meaning
BRAINLESS_VAULT	Where your vault lives. Default: the checkout the tools run from.
BRAINLESS_OUTPUT_LANG	Overrides output_lang from PROFILE.md. Any ISO code. See Localization.
BRAINLESS_LLM_PROVIDER	claude-cli (default), anthropic, ollama, openai, grok, gemini, openrouter, openai-compatible, codex-cli, gemini-cli or goose. Per lane: _<LANE>.
BRAINLESS_LLM_BASE_URL	For openai-compatible: the endpoint. The named providers know theirs; BRAINLESS_<NAME>_BASE_URL moves one (Ollama on another box).
BRAINLESS_LLM_MODEL	The model for every provider except claude-cli and goose. Per lane: _<LANE>.
BRAINLESS_FOLDER_<ROLE>	The folder for a role: INBOX, DAILY, LIBRARY, THINKING, BELIEFS, DECISIONS, IDEAS.
BRAINLESS_DAILY_HOUR	Lite: the hour from which the evening digest and compile run. Default 21.
BRAINLESS_SEARCH	bm25, hybrid or rerank. Default: hybrid when a semantic index exists, else bm25. rerank measured worse and slower; it stays opt-in.
BRAINLESS_EMBED_MODEL	The embedding model for the semantic index. Default intfloat/multilingual-e5-large. A change needs a fresh semantic_index.py build and a look at retrieval_eval.py first.
BRAINLESS_VECTOR_WEIGHT	The embedding list's vote in the fusion, relative to BM25. Default 1.0.
FASTEMBED_CACHE_PATH	Where the embedding model is kept. Default ~/.cache/fastembed, not the system temp dir, which macOS empties.

3. Choosing a backend

brainless init asks. By hand, in brainless.toml or the environment:

export BRAINLESS_LLM_PROVIDER=ollama          # or anthropic, grok, codex-cli, ...
export BRAINLESS_LLM_MODEL=qwen3:8b
python3 tools/llm.py --models ollama          # what a provider serves
python3 tools/llm.py --probe compile          # one throwaway call through a lane

The full deployment's default is still the claude CLI signed in with a subscription. The model table, with what each choice can and cannot do, is on Lite.

The text-processing LLM never gets file tools regardless of backend: context is embedded in the prompt. That fence is what makes an unattended run safe. See Ownership and Privacy.

4. Addon secrets

Each addon reads its own credentials from ~/.config/brainless/, never from the repo. A missing secret makes the addon a no-op, so every scheduler is safe to install before you decide to use one.

File	Addon
telegram_token, telegram_chat_id	Telegram capture (inbox only; nothing is sent back)
pipedrive_api_token (and optional crm_provider, crm_pipelines, crm_owner)	CRM Snapshot
buzz/<persona>.env	Buzz persona agents (see Reference Deployment)
mcp_token	The bearer token for tools/mcp_server.py --http. Created on first start, mode 600.

Scheduling

Lite: brainless schedule install (or yes to the question in brainless init) adds one entry, a launchd agent or a systemd user timer, that runs brainless tick every 15 minutes; the queue decides what is due. brainless queue shows it.

Full: install.sh --profile full --schedule installs the recurring jobs: launchd agents on macOS, systemd user timers on Linux. The full schedule and the worker unit files are on Reference Deployment. Every script the timers call is described in the Scripts Reference.