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

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, at its own thinking level. 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. Must be positive and fit the model's context window. When unset, Vibe derives it from each model's context window
`compaction_max_output_tokens`	number	`0`	Output token cap for compaction requests, on any provider. Vibe keeps it within the compaction model's maximum output and the room its context window leaves. `0` sends a cap only to providers that require one
`compaction_reasoning_limit_tokens`	number	`32000`	Approximate reasoning tokens after which Vibe abandons the first compaction request for a shorter fallback request. `0` disables the limit
`agent_max_output_tokens`	number	`0`	Output token cap for agent and subagent requests, on any provider. Vibe keeps it within the model's maximum output and the room its context window leaves. `0` sends a cap only to providers that require one
`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
`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`
`outside_workdir`	string	`"ask"`	`"ask"` prompts before a file or shell tool reaches outside the working directory. `"deny"` refuses the call, and the agent keeps working. See Access outside the working directory
`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
`max_subagents`	number	`32`	Maximum number of subagents alive at once
`max_concurrent_subagents`	number	`32`	Maximum number of subagents running at the same time
`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	`300`	Seconds of silence, once the model starts answering, before Vibe treats the response as stalled and retries it
`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
`enable_mouse_capture`	boolean	`true`	Captures the mouse for clicks, scrolling, and selection. Set to `false` to select and copy with your terminal instead. See Select and copy text
`show_thinking_nodes`	boolean	`true`	Shows the model's reasoning in the chat, as a collapsible "Thought" row
`file_watcher_for_autocomplete`	boolean	`true`	Refreshes `@` file suggestions and picks up new or edited skills when files change
`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
`experimental_worktree_copy_on_write`	boolean	`false`	Experimental, macOS only. Creates new worktrees of a trusted repository from a template checkout, so they take less disk space and are created faster
`log_level`	string	`"WARNING"`	Log level for `~/.vibe/logs/vibe.log`: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`. Change it with `/log-level`
`strict_config`	boolean	`false`	Refuses to start when the configuration has settings Vibe doesn't use, such as misspelled keys. See Check your configuration
`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, raise_on_compaction_failure, include_model_info, include_prompt_detail, api_connect_timeout, api_write_timeout, and api_pool_timeout 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. Vibe no longer loads custom Python tools, and removes tool_paths from config.toml at startup.

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"`)
`preserve_api_base`	boolean	`false`	Keeps the configured `api_base` when sign-in or `/reload` would replace it with the one your deployment advertises. Use it when you reach the API through a proxy. See Check the `/whoami` domains
`[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		The model's maximum output tokens. Providers that require an output limit, such as Anthropic, receive it as the cap unless `agent_max_output_tokens` or `compaction_max_output_tokens` is set
`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		Default thinking level for the model: `off`, `low`, `medium`, `high`, `xhigh`, `max`, or a level from `thinking_levels`. Vibe sends it to the provider as written, with a warning when it's none of these. When unset, the model's lowest level
`thinking_levels`	array<string>		Thinking levels `/thinking` offers for this model, lowest first. Can include levels specific to the provider, such as `["low", "turbo"]`. When omitted, the model's known levels
`supports_images`	boolean		Whether the model is vision-capable. When `true`, you can `@`-mention images
`max_context_length`	number		Context window in tokens. Drives automatic compaction
`auto_compact_threshold`	number		Token count that triggers automatic compaction. Overrides the default, derived from `max_context_length`

When these fields are unset, Vibe takes them from the provider or from its list of known models. For an unknown model, it assumes a 262,144-token context window and shows a warning.

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
`outside_workdir`	string	Top-level `outside_workdir`	`"ask"` or `"deny"` for this tool's access outside the working directory. Overrides the top-level setting
`default_timeout`	number		Shell tools only. Default command timeout, in seconds. Without `max_timeout_seconds`, at most `300`
`max_timeout_seconds`	number		Shell tools only. Longest command timeout the agent can request, in seconds. Set it together with `default_timeout`

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 or subagent (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

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
`VIBE_STRICT_CONFIG`	Set to `1` for the same effect as `strict_config = true`
`VIBE_TERMINAL_KEY`	Names the terminal that `--continue` follows. Set it to an empty value to ignore the terminal. See Continue or resume sessions
`VIBE_CUSTOM_CONSOLE_URL`	Set by administrators to pin the console used for browser sign-in. See Pin the sign-in console
`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.

Configuration reference

Top-level keys

Providers ([[providers]])

Models ([[models]])

Utility models ([utility_models])

Session logging ([session_logging])

MCP servers ([[mcp_servers]])

Connectors ([[connectors]])

Per-tool permissions ([tools.<tool_name>])