Skip to content

Instantly share code, notes, and snippets.

@chris-hatton

chris-hatton/vibe_config_guide.md

Last active December 11, 2025 11:45
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save chris-hatton/6e1a62be8412473633f7ef02d067547d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save chris-hatton/6e1a62be8412473633f7ef02d067547d to your computer and use it in GitHub Desktop.
Download ZIP
Mistral Vibe `config.toml` guide (reverse engineered by Le Chat)
Raw
vibe_config_guide.md

Based on config.py from Mistral Vibe, here’s a reverse-engineered documentation for the config.toml format and its editing. This file is used to configure the "vibe" application, which appears to be a CLI or agent-based tool for interacting with AI models, tools, and project contexts.

config.toml Documentation

File Location

  • The global config file is located at:
    • $VIBE_HOME/config.toml (if $VIBE_HOME is set)
    • Otherwise: ~/.vibe/config.toml
  • Project-specific config files can be placed in a .vibe/config.toml file in any parent directory of the current working directory.

Structure of config.toml

The config.toml file is structured as a TOML document with the following top-level sections:

1. Core Configuration

Key Type Default Description
active_model string "devstral-2" Alias of the active model.
vim_keybindings bool false Enable Vim-style keybindings.
disable_welcome_banner_animation bool false Disable the welcome banner animation.
displayed_workdir string "" Directory displayed in the UI.
auto_compact_threshold int 200_000 Threshold for auto-compacting.
context_warnings bool false Show context warnings.
textual_theme string "textual-dark" Theme for the textual UI.
instructions string "" Custom instructions for the agent.
workdir string None Working directory (absolute or relative).
system_prompt_id string "cli" ID of the system prompt (built-in or custom .md file).
include_commit_signature bool true Include commit signature in context.
include_model_info bool true Include model info in context.
include_project_context bool true Include project context.
include_prompt_detail bool true Include prompt details.
enable_update_checks bool true Enable update checks.
api_timeout float 720.0 API timeout in seconds.

2. Providers

Key Type Description
providers list of objects List of provider configurations.

Provider Object

Key Type Default Description
name string - Name of the provider (e.g., "mistral", "llamacpp").
api_base string - Base URL for the provider's API.
api_key_env_var string "" Environment variable for the API key.
api_style string "openai" API style (e.g., "openai").
backend string "GENERIC" Backend type ("MISTRAL" or "GENERIC").

Example:

[[providers]]
name = "mistral"
api_base = "https://api.mistral.ai/v1"
api_key_env_var = "MISTRAL_API_KEY"
backend = "MISTRAL"

3. Models

Key Type Description
models list of objects List of model configurations.

Model Object

Key Type Default Description
name string - Name of the model.
provider string - Name of the provider (must match a provider in providers).
alias string - Alias for the model (defaults to name).
temperature float 0.2 Temperature for sampling.
input_price float 0.0 Price per million input tokens.
output_price float 0.0 Price per million output tokens.

Example:

[[models]]
name = "mistral-vibe-cli-latest"
provider = "mistral"
alias = "devstral-2"
input_price = 0.4
output_price = 2.0

4. Project Context

Key Type Default Description
max_chars int 40_000 Max characters in project context.
default_commit_count int 5 Default number of commits to include.
max_doc_bytes int 32_768 Max bytes per document.
truncation_buffer int 1_000 Buffer for truncation.
max_depth int 3 Max directory depth.
max_files int 1000 Max files to include.
max_dirs_per_level int 20 Max directories per level.
timeout_seconds float 2.0 Timeout for operations.

Example:

[project_context]
max_chars = 40000
default_commit_count = 5

5. Session Logging

Key Type Default Description
save_dir string "$VIBE_HOME/logs/session" Directory to save session logs.
session_prefix string "session" Prefix for session log files.
enabled bool true Enable session logging.

Example:

[session_logging]
save_dir = "~/.vibe/logs/session"
enabled = true

6. Tools

Key Type Description
tools object Dictionary of tool configurations.
tool_paths list of strings Additional directories to search for custom tools.
enabled_tools list of strings List of tools to enable (supports glob/regex patterns).
disabled_tools list of strings List of tools to disable (supports glob/regex patterns).

Example:

[tools]
my_tool = { param1 = "value1", param2 = "value2" }

tool_paths = ["/path/to/tools"]

enabled_tools = ["tool1", "tool2"]
disabled_tools = ["tool3"]

7. MCP Servers

Key Type Description
mcp_servers list of objects List of MCP server configurations.

MCP Server Object

Key Type Description
name string Name of the MCP server.
transport string Transport type ("http", "streamable-http", "stdio").
url string Base URL for HTTP transport.
headers object Additional HTTP headers.
api_key_env string Environment variable for API key.
api_key_header string Header for API key.
api_key_format string Format for API key header.
command string/list Command for stdio transport.
args list Arguments for stdio transport.

Example:

[[mcp_servers]]
name = "my_mcp"
transport = "http"
url = "http://localhost:8000"
headers = { Authorization = "Bearer token" }

Editing config.toml

  1. Manual Editing: Open the file in a text editor and modify the values as needed.
  2. Programmatic Updates: Use the VibeConfig.save_updates() method to merge changes into the existing config.
  3. Validation: The config is validated using Pydantic, so ensure all required fields are present and correct.

Example config.toml

active_model = "devstral-2"
vim_keybindings = false
textual_theme = "textual-dark"

[[providers]]
name = "mistral"
api_base = "https://api.mistral.ai/v1"
api_key_env_var = "MISTRAL_API_KEY"
backend = "MISTRAL"

[[models]]
name = "mistral-vibe-cli-latest"
provider = "mistral"
alias = "devstral-2"
input_price = 0.4
output_price = 2.0

[project_context]
max_chars = 40000
default_commit_count = 5

[session_logging]
save_dir = "~/.vibe/logs/session"
enabled = true

[tools]
my_tool = { param1 = "value1" }
tool_paths = ["/path/to/tools"]
enabled_tools = ["tool1"]

Extended example: Configure a custom OpenAPI-compatible provider

To define a custom model in your config.toml that connects to a custom OpenAPI-compatible endpoint (e.g., a local or self-hosted model server running on a non-standard port) with a custom model ID, you need to:

  1. Define a new provider (if your endpoint is not already covered by an existing provider).
  2. Define a new model that uses this provider and specifies your custom model ID.

Step-by-Step Guide

1. Define a Custom Provider

Add a new provider entry in the providers section. This provider should point to your custom endpoint and specify the environment variable for the API key (if required).

[[providers]]
name = "my_custom_provider"  # Unique name for your provider
api_base = "http://localhost:1234/v1"  # Replace with your endpoint and port
api_key_env_var = "MY_CUSTOM_API_KEY"  # Optional: if your endpoint requires an API key
backend = "GENERIC"  # Use "GENERIC" unless it's a Mistral-compatible API
  • Replace http://localhost:1234/v1 with your actual endpoint and port.
  • If your endpoint does not require an API key, set api_key_env_var = "".

2. Define a Custom Model

Add a new model entry in the models section. This model should reference your custom provider and specify your custom model ID.

[[models]]
name = "my-custom-model"  # Name of the model (for internal reference)
provider = "my_custom_provider"  # Must match the provider name above
alias = "my-custom-model"  # Alias for easy reference (e.g., in active_model)
temperature = 0.7  # Optional: adjust as needed
input_price = 0.0  # Optional: set pricing if applicable
output_price = 0.0
  • name: A descriptive name for your model (e.g., "my-local-llama").
  • provider: Must match the name of your custom provider.
  • alias: A short alias for easy reference (e.g., "local" or "my-custom-model").
  • temperature: Optional, adjust as needed.
  • input_price and output_price: Optional, set to 0.0 if not applicable.

3. Set the Custom Model as Active

Set your custom model as the active model:

active_model = "my-custom-model"  # Must match the alias of your custom model

Full Example

Here’s a complete example of a config.toml snippet for a custom model:

active_model = "my-custom-model"

[[providers]]
name = "my_custom_provider"
api_base = "http://localhost:1234/v1"
api_key_env_var = "MY_CUSTOM_API_KEY"  # Omit or set to "" if no API key is needed
backend = "GENERIC"

[[models]]
name = "my-local-llama"
provider = "my_custom_provider"
alias = "my-custom-model"
temperature = 0.7
input_price = 0.0
output_price = 0.0

Notes

  • Environment Variables: If your endpoint requires an API key, ensure the environment variable (e.g., MY_CUSTOM_API_KEY) is set in your shell or in the .env file in your VIBE_HOME directory.
  • OpenAPI Compatibility: Ensure your custom endpoint is compatible with the OpenAPI specification expected by the tool (e.g., /v1/chat/completions or similar).
  • Ports and Protocols: Use http:// or https:// as appropriate, and specify the correct port.
  • Validation: The tool will validate the config on startup. If the provider or model is misconfigured, it will raise an error.

Troubleshooting

  • If you get a "Missing API Key" error, ensure the environment variable is set and matches the api_key_env_var in your provider.
  • If you get a "Wrong Backend" error, ensure backend = "GENERIC" unless you are using a Mistral-compatible API.
  • If the model is not found, double-check the alias and provider names for typos.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment