Vorto configuration overview: config.toml and file locations

Vorto reads a single TOML file at startup and merges it onto its built-in defaults. You don’t need to create the file to use Vorto — every setting has a sensible default — but the file is your primary way to tune editor behavior, cursor shapes, keybindings, language settings, and LSP servers. You can re-read the file without restarting by running :config-reload. It re-applies the settings that can change live — keymap, cursor shapes, [editor] / [finder] options, the agent catalog, grammar recipes, and the active theme. Already-running subsystems (LSP servers, syntax and preview workers) keep their startup snapshot and need a restart. See Commands.

Config file location

The global config file lives at:

$XDG_CONFIG_HOME/vorto/config.toml

When $XDG_CONFIG_HOME is not set, Vorto falls back to ~/.config/vorto/config.toml.

Workspace-local config

You can add a project-local config that overrides your global settings for that directory. Vorto checks the current working directory for two layouts:

Path	Description
`.vorto/config.toml`	Directory form — mirrors the global `~/.config/vorto/` layout
`.vorto`	Single TOML file — simpler alternative

Workspace-local config takes full precedence over the global config. Only one config file is active at a time.

Config directory structure

~/.config/vorto/
├── config.toml       # editor settings, keybindings, language overrides
├── grammars/         # installed tree-sitter .so / .dylib / .dll libraries
├── queries/
│   └── <lang>/       # highlights.scm, indents.scm, etc. per language
└── themes/
    └── <name>.toml   # your color themes (shadow built-ins of the same name)

The grammars/ and queries/ directories can be overridden with grammar_dir and query_dir keys at the top level of config.toml.

Top-level TOML sections

Section	Purpose
`[editor]`	Global editor settings (indent width, whitespace rendering, etc.)
`[cursor]`	Cursor shape and blinking per mode
`[[bind]]`	Custom keybindings — each entry maps a key sequence to an action
`[languages.<name>]`	Per-language overrides for editor settings, grammar, LSP, and formatter
`[lsp.<name>]`	LSP server definitions — override built-ins or add new servers
`[grammars.<name>]`	Tree-sitter grammar recipes for languages outside the built-in catalog
`[agent]` / `[agents.<name>]`	The default AI agent and command-line catalog for the `:agent` launcher

Minimal complete example

[editor]
indent_width = 2
tab_width = 4
format_on_save = true

[cursor]
normal = "block"
insert = "bar"
blinking = false

[[bind]]
keys = "<C-s>"
action = "save"

[[bind]]
keys = "<space>w"
action = "save"

[languages.rust]
indent_width = 4
tab_width = 4

[lsp.rust-analyzer]
args = ["--log-file", "/tmp/ra.log"]

Get Started

Editing

Languages

LSP

Configuration

Troubleshooting

Vorto configuration overview: config.toml and file locations

Config file location

Workspace-local config

Config directory structure

Top-level TOML sections

Minimal complete example

Further reading

​Config file location

​Workspace-local config

​Config directory structure

​Top-level TOML sections

​Minimal complete example

​Further reading

Config file location

Workspace-local config

Config directory structure

Top-level TOML sections

Minimal complete example

Further reading