Configuration Schema

Caboose uses TOML configuration files with a layered override system. Project-level settings take precedence over global defaults, and CLI flags override both.

Most of these values are managed automatically through the TUI — /connect saves API keys, /model updates the default provider, /mcp toggles servers, and /settings adjusts behavior options. This reference is for when you want to edit the files directly or understand what each field does.

Config file locations

File	Purpose
~/.config/caboose/config.toml	Global defaults (apply to all projects)
.caboose/config.toml	Project overrides (checked into version control)
~/.config/caboose/auth.json	API keys and secrets (never commit this)

Project config is merged on top of global config field-by-field. Unset project fields inherit the global value.

Authentication

API keys are stored in ~/.config/caboose/auth.json, not in config files. You can also set them via environment variables.

{
  "anthropic": "sk-ant-...",
  "openai": "sk-..."
}

Supported environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OLLAMA_HOST.

Full schema reference

[provider]

Top-level provider settings.

Field	Type	Default	Description
default	string	"anthropic"	Default provider to use. One of anthropic, openai, gemini, ollama.
model	string	"claude-sonnet-4"	Default model across all providers.

[provider.<name>]

Per-provider overrides. Supported sections: provider.anthropic, provider.openai, provider.gemini, provider.ollama.

Field	Type	Default	Description
model	string	(inherits provider.model)	Model to use for this specific provider.

[tools]

Field	Type	Default	Description
allow	string[]	(all built-in tools)	Allowlist of tool names the agent may use. Built-in tools: read_file, write_file, edit_file, glob, grep, bash, list_directory, fetch.

[behavior]

Field	Type	Default	Description
auto_handoff_prompt	bool	true	Prompt user to hand off when context reaches 90% capacity.
max_session_cost	float	(off)	Pause the agent when cumulative session cost reaches this dollar amount.

[memory]

Field	Type	Default	Description
enabled	bool	true	Enable persistent memory across sessions.

[skills]

Field	Type	Default	Description
enabled	bool	true	Enable the skills system.

[mcp.servers.<name>]

Register custom MCP servers. Each server entry requires a command and optional arguments.

Field	Type	Default	Description
command	string	(required)	Executable to launch the MCP server.
args	string[]	[]	Arguments passed to the command.
disabled	bool	false	Temporarily disable this server without removing its config.

[mcp.presets.<name>]

Override built-in MCP presets (e.g. fetch, context7).

Field	Type	Default	Description
disabled	bool	false	Disable a built-in preset.
removed	bool	false	Hide a preset entirely so it never loads.

[server]

Embedded WebSocket server for mobile and web clients.

Field	Type	Default	Description
enabled	bool	false	Start the embedded server on launch.
port	int	9090	Port to listen on.
bind	string	"127.0.0.1"	Bind address.

[background_agents]

Budget and concurrency settings for background agents spawned via /bg.

Field	Type	Default	Description
max_agents	int	3	Maximum concurrent background agents.
per_agent_budget	int	100000	Per-agent token budget.
global_budget	int	500000	Global token budget across all background agents.

[services.web_search]

Web search backend configuration for the web_search tool.

Field	Type	Default	Description
provider	string	(required)	Backend to use: "searxng" or "tavily".
base_url	string	(required for searxng)	URL of your SearXNG instance.
user_agent	string	"Caboose/1.0 (SearchService)"	User-Agent header for SearXNG requests.
api_key_env	string	"TAVILY_API_KEY"	Environment variable containing the Tavily API key.
max_results	int	5	Maximum search results to return.
enabled	bool	true	Enable or disable this service.

Complete example

[provider]
default = "anthropic"
model = "claude-sonnet-4"

[provider.anthropic]
model = "claude-sonnet-4"

[provider.openai]
model = "gpt-4.1"

[tools]
allow = ["read_file", "write_file", "edit_file", "glob", "grep", "bash", "list_directory", "fetch"]

[behavior]
auto_handoff_prompt = true
max_session_cost = 10.0

[memory]
enabled = true

[skills]
enabled = true

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

[mcp.servers.context7]
disabled = false

[mcp.presets.fetch]
removed = true

[server]
enabled = false
port = 9090
bind = "127.0.0.1"

[background_agents]
max_agents = 3
per_agent_budget = 100000
global_budget = 500000

[services.web_search]
provider = "searxng"
base_url = "https://search.example.com"
user_agent = "Caboose/1.0 (SearchService)"
max_results = 5