Configuration reference
An exhaustive index of every key accepted by config.toml and the agent-definition files. Keys are grouped by section, each linking to the page that explains the concept in depth. Use this as a lookup; use Configuration to learn how the file works.
Top-level keys
Top-level keys
All keys live at the root of config.toml unless noted.
| Key | Type | Default | Description |
|---|---|---|---|
default_agent | string | "accept-edits" | Agent used when you don't pass --agent, in interactive and programmatic sessions. See Agents |
active_model | string | Model alias currently in use. Set to a [[models]] alias or a built-in model ID | |
allowed_models | array<string> | Allow-list of model name patterns (exact, glob, or re: regex), matched against the model names sent to the inference API, not their aliases. When non-empty, only matching models are selectable | |
compaction_model | table | Model that summarizes the conversation during /compact and automatic compaction. Must use the active model's provider; otherwise Vibe warns and uses the active model. Defaults to the active model | |
auto_compact_threshold | number | Token count that triggers automatic compaction for models that don't set their own. Ignored for a model when it's at or above the model's max_context_length. When unset, models compact at 80% of max_context_length, or at 200,000 tokens when the window is unknown. 0 disables automatic compaction | |
compaction_max_output_tokens | number | 80000 | Output token cap for compaction requests. Never exceeds the model's own output cap. 0 gives compaction the same cap as other requests |
compaction_thinking | string | Thinking level for the first compaction request: off, low, medium, high, or max. When unset, the compaction model keeps its own level. The fallback request always runs without reasoning | |
compaction_reasoning_limit_tokens | number | 32000 | Approximate reasoning tokens after which Vibe abandons the first compaction request for a simpler fallback request without tools or reasoning. 0 disables the limit |
output_limit_retries | number | 6 | Number of times per turn Vibe discards an answer cut off at the output token limit and asks for it again, with feedback asking for a shorter response. 0 ends the turn on the first cut-off answer |
output_token_reserve | number | 4096 | Tokens kept free when Vibe lowers a request's output cap to fit the room its input leaves in the context window. Applies to models that set max_context_length |
vision_model | table | Vision-capable model that describes attached images when the active model doesn't support images. Defaults to any vision-capable model on the provider of the active model. Set it to use a model from another provider | |
enabled_agents | array<string> | Allow-list of agent name patterns. When non-empty, only matching agents are available | |
disabled_agents | array<string> | Deny-list of agent name patterns, applied when enabled_agents is empty | |
agent_paths | array<string> | Extra directories to discover custom agents from | |
system_prompt_id | string | "cli" | System prompt to use. Set it to the name of a Markdown file in ~/.vibe/prompts/ or .vibe/prompts/, without the .md extension |
compaction_prompt_id | string | "compact" | Prompt used to summarize the conversation during compaction. Resolved like system_prompt_id |
title_prompt_id | string | "session_title" | Prompt used to generate session titles. Resolved like system_prompt_id |
skill_paths | array<string> | Extra directories to discover skills from. See Skills | |
enabled_skills | array<string> | Allow-list of skill name patterns (exact, glob, or re: regex). When non-empty, only matching skills load | |
disabled_skills | array<string> | Deny-list of skill name patterns, applied when enabled_skills is empty | |
enabled_tools | array<string> | Allow-list of tool name patterns. See Safety, approvals, and permissions | |
disabled_tools | array<string> | Deny-list of tool name patterns, applied after enabled_tools | |
enable_mcp | boolean | true | Allows MCP servers. When false, Vibe blocks adding, removing, enabling, signing in to, and loading tools from MCP servers, including servers provided by plugins. See Admin config |
enable_connectors | boolean | true | Allows connectors, including the built-in web search. See Block connectors |
enable_auto_approve | boolean | true | Allows the auto-approve mode. When false, Vibe hides the auto-approve agent and every custom agent with safety = "yolo", and ignores --auto-approve, --yolo, and bypass_tool_permissions. Per-tool permissions still apply. Meant for admin config |
enable_subagents | boolean | true | Lets the agent delegate work to subagents. See Agents |
enable_background_processes | boolean | true | Lets the agent run commands in the background. When false, commands run to completion in the foreground |
enable_update_checks | boolean | true | Checks once a day for a new release and offers to install it |
enable_notifications | boolean | true | Rings the terminal bell and updates the terminal title when Vibe finishes or needs your input while the terminal isn't focused |
enable_telemetry | boolean | true | Sends anonymous usage and error telemetry to Mistral. Disable for offline-only setups |
enable_system_trust_store | boolean | false | Validates HTTPS certificates against the operating system trust store instead of Vibe's bundled roots. See Corporate certificate authorities |
api_stream_idle_timeout | number | 0 | Seconds of silence, once the model starts answering, before Vibe treats the response as stalled. 0 disables the limit |
ask_confirmation_on_exit | boolean | true | Asks for a second Ctrl+D before quitting. Ctrl+C always asks |
autocopy_to_clipboard | boolean | true | Copies text to the clipboard when you release a mouse selection |
cursor_blink | boolean | true | Blinks the input cursor. Set to false for a steady cursor |
theme | string | "auto" | Terminal theme. auto follows the terminal background or the OS light or dark preference. Change it with /theme |
show_subagent_status_list | boolean | true | Shows the list of running subagents above the prompt |
worktree_limit | number | 15 | Maximum number of recent Vibe-managed git worktrees kept locally |
log_level | string | "WARNING" | Log level for ~/.vibe/logs/vibe.log: DEBUG, INFO, WARNING, ERROR, or CRITICAL. Change it with /log-level |
experimental_enable_model_catalog | boolean | false | Experimental. Fetches Mistral's curated model catalog at session start and adds its models to the model list. Your [[models]] presets still override their settings. When you haven't picked a model, Vibe runs the catalog's recommended model, unless an experiment assigns you another one |
[[providers]] | table array | Provider presets. Fields listed below. See API keys and profiles | |
[[models]] | table array | Model presets. Fields listed below. See API keys and profiles | |
[[mcp_servers]] | table array | MCP server definitions. Fields listed below. See MCP servers | |
[utility_models] | table | Models for background tasks such as the smart approve classifier and session titles. Fields listed below | |
[session_logging] | table | Session storage settings. Fields listed below |
displayed_workdir, context_warnings, and raise_on_compaction_failure are deprecated. Vibe still accepts them in existing files, but they have no effect. enable_auto_update has no effect either: use enable_update_checks.
Providers (
[[providers]])Providers ([[providers]])
One [[providers]] table per provider preset.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | Required | Provider preset identifier, referenced by a [[models]] provider |
api_base | string | Required | Base URL for the provider's API |
api_key_env_var | string | Environment variable name holding the API key. Secrets must use this form in admin config | |
api_style | string | "openai" | API style: "openai", "openai-responses", "reasoning", "anthropic", or "vertex-anthropic" |
backend | string | "generic" | Backend type: "generic" or "mistral" |
region | string | Google Cloud region for Vertex AI (api_style = "vertex-anthropic"). Requires project_id | |
project_id | string | Google Cloud project for Vertex AI (api_style = "vertex-anthropic") | |
[providers.extra_headers] | table | Subtable of extra HTTP headers, for example "x-acme-tenant" = "engineering" |
Models (
[[models]])Models ([[models]])
One [[models]] table per model preset.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | Required | Model ID, for example mistral-medium-latest |
provider | string | Required | References a [[providers]] name |
alias | string | name | Local alias used by active_model. Defaults to name when omitted |
display_name | string | alias | Label shown in the model picker. Falls back to alias when unset |
temperature | number | 0.2 | Sampling temperature |
top_p | number | Nucleus sampling, between 0 (excluded) and 1. Unset leaves the provider's default | |
max_output_tokens | number | Maximum output tokens per model request. Unset leaves the provider's default | |
input_price | number | Per-million input token cost, used to cap costs in programmatic mode | |
output_price | number | Per-million output token cost, used to cap costs in programmatic mode | |
cached_input_price | number | Per-million cached input token cost. Omit to bill cached input at input_price | |
thinking | string | off | Default thinking level for the model. One of the model's thinking_levels |
thinking_levels | array<string> | Thinking levels available for this model. Defaults to off, low, medium, high, and max when omitted | |
supports_images | boolean | false | Whether the model is vision-capable. When true, you can @-mention images |
max_context_length | number | Context window in tokens. Drives automatic compaction, and lowers each request's output cap to the room its input leaves, minus output_token_reserve | |
auto_compact_threshold | number | Token count that triggers automatic compaction. Overrides the default trigger, 80% of max_context_length |
Utility models (
[utility_models])Utility models ([utility_models])
Models for background tasks, one key per task. Each value is the alias of a [[models]] preset, or "active" to use the session's model. When a key is unset, Vibe uses a small, fast Mistral model if your Mistral provider serves one, and the session's model otherwise. If an alias doesn't match a configured model, or allowed_models excludes it, Vibe shows a warning and uses that automatic selection instead.
| Key | Type | Default | Description |
|---|---|---|---|
smart_approve | string | Automatic | Model that classifies tool calls for the smart-approve agent. See Choose the smart approve model |
title | string | Automatic | Model that generates session titles |
Session logging (
[session_logging])Session logging ([session_logging])
Controls where Vibe saves sessions. --continue, --resume, and /resume need saved sessions. See Work with the CLI.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Saves sessions to disk |
save_dir | string | ~/.vibe/logs/session | Directory where sessions are saved |
generate_titles | boolean | true | Generates session titles in the background. When false, Vibe shows the first message instead |
MCP servers (
[[mcp_servers]])MCP servers ([[mcp_servers]])
One [[mcp_servers]] table per server. Required fields depend on the transport (http, streamable-http, or stdio).
| Key | Type | Default | Description |
|---|---|---|---|
name | string | Required | Short alias; prefixes this server's tool names |
transport | string | Required | One of http, streamable-http, or stdio |
url | string | Base URL for HTTP transports | |
command | string | Command for the stdio transport | |
args | array<string> | Arguments for the stdio transport | |
env | table | Environment variables passed to the stdio process | |
startup_timeout_sec | number | 10 | Seconds to wait for the server to start |
tool_timeout_sec | number | 60 | Seconds to wait for a tool call to complete |
disabled | boolean | false | Hides all tools from this server. /mcp toggles it |
disabled_tools | array<string> | Tool names, without the server prefix, to hide from this server | |
[mcp_servers.auth] | table | Authentication for HTTP transports. Fields listed below |
The [mcp_servers.auth] table sets how Vibe authenticates to an HTTP server:
| Key | Type | Default | Description |
|---|---|---|---|
type | string | "static" | "static" for headers or an API key, "oauth" for browser sign-in |
headers | table | static only. Extra HTTP headers | |
api_key_env | string | static only. Env var holding the API key. Distinct from providers' api_key_env_var | |
api_key_header | string | "Authorization" | static only. Header name to set with the API key |
api_key_format | string | "Bearer {token}" | static only. Format string for the header value |
scopes | array<string> | Required for oauth | oauth only. OAuth scopes to request. Pass an empty list to accept the server's default |
client_id | string | oauth only. Pre-registered public client ID, with http://127.0.0.1:<redirect_port>/callback as its redirect URI. Can't be combined with client_metadata_url. Without either, Vibe registers a client dynamically | |
client_metadata_url | string | oauth only. HTTPS URL of a client metadata document, with a path other than /. The document must list http://127.0.0.1:<redirect_port>/callback in redirect_uris. Used only if the server advertises client_id_metadata_document_supported; otherwise Vibe registers a client dynamically. Can't be combined with client_id | |
redirect_port | integer | 47823 | oauth only. Local port for the sign-in callback, from 1024 to 65535. Change it if 47823 is already in use |
Vibe still accepts headers, api_key_env, api_key_header, and api_key_format at the top level of [[mcp_servers]] and treats them as static authentication.
Connectors (
[[connectors]])Connectors ([[connectors]])
One [[connectors]] table per connector you want to change. /connectors writes these entries when you enable or disable a connector or tool.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | Required | Connector name, as listed in /connectors (for example, web_search) |
disabled | boolean | false | Hides all tools from this connector |
disabled_tools | array<string> | Tool names, without the connector prefix, to hide from this connector |
Per-tool permissions (
[tools.<tool_name>])Per-tool permissions ([tools.<tool_name>])
<tool_name> is a built-in tool (read_file, bash, etc.), an MCP tool named {server_name}_{tool_name}, or a connector tool named connector_{connector_name}_{tool_name}. One block per tool.
| Key | Type | Default | Description |
|---|---|---|---|
permission | string | "always" to auto-allow the tool, "ask" to prompt before use, "never" to block it | |
allowlist | array<string> | Read-only commands for bash | Allowed without approval. For bash, command prefixes such as ["git status", "pnpm test"]. For read_file, write_file, and edit, globs matched against absolute paths, such as ["/home/me/project/docs/*"]. Replaces the default list |
denylist | array<string> | Interactive commands for bash | Always denied. For bash, command prefixes such as ["rm -rf"]. For read_file, write_file, and edit, globs matched against absolute paths. Replaces the default list |
Agent definition files
Agent definition files
These keys live in ~/.vibe/agents/<name>.toml or ./.vibe/agents/<name>.toml, not in config.toml. They define custom agents and subagents. Most top-level keys above (active_model, enabled_tools, disabled_tools, [tools.*] blocks) can also be set inside an agent file to override the global config for that agent.
| Key | Type | Default | Description |
|---|---|---|---|
agent_type | string | "agent" | "agent" (user-facing, selectable via --agent) or "subagent" (delegation-only) |
display_name | string | Human-readable label | |
description | string | Free-text description. Required for subagents | |
instructions | string | Prompt text written inline. For an agent, appended after the system prompt. For a subagent, replaces the system_prompt_id prompt | |
safety | string | "neutral" | Visual hint: safe, neutral, destructive, smart, or yolo. Changes the input border color; does not enforce permissions. enable_auto_approve = false hides yolo agents |
system_prompt_id | string | Names a Markdown prompt file in ./.vibe/prompts/ (trusted folders only) or ~/.vibe/prompts/, without the .md extension | |
active_model | string | Model alias for this agent (same key as global config) | |
enabled_tools | array<string> | Tool allow-list for this agent | |
disabled_tools | array<string> | Tool deny-list for this agent |
See Agents for built-in agents and full examples.
Environment variables
Environment variables
Not config.toml keys, but part of the configuration model. See Configuration precedence for where VIBE_<KEY> variables sit.
| Variable | Purpose |
|---|---|
VIBE_HOME | Overrides the ~/.vibe/ home directory for all state (config, prompts, agents, skills, logs) |
VIBE_<KEY> | Overrides the top-level config key <key>, for example VIBE_ACTIVE_MODEL. Use __ for nested keys. Vibe ignores and logs a value it can't parse |
MISTRAL_API_KEY | Primary Mistral API key |
<PROVIDER>_API_KEY | API key referenced by a [[providers]] api_key_env_var (for example OPENROUTER_API_KEY) |
See Configuration precedence and Admin config for how these layers combine.