Vector Docs

Reference

Configuration files

Vector's settings are JSON files named vector.json, or vector.jsonc, which may carry comments. Some of the desktop app's Settings, such as a custom provider or a subagent switch, save to one of these files for you (see below for which), and the keys this page lists are ones you can write yourself. Start a file with "$schema": "https://vectordev.ai/config.json" for completion and checks in your editor.

Where Vector reads them

A repository
vector.json or vector.jsonc in the folder you work in and in each folder above it up to the repository's root, and the same names in the repository's .vector folders. Keys that could run code or send your work elsewhere apply once you trust the repository; see Before you trust a repository.
Every repository, in the desktop app
The desktop app has two config folders of its own. Its Settings save to vector.jsonc, or to vector.json when only that one exists, in ~/Library/Application Support/ai.vector.app/xdg-config/vector/ on macOS, %APPDATA%\ai.vector.app\xdg-config\vector\ on Windows and ~/.config/ai.vector.app/xdg-config/vector/ on Linux (in vector under XDG_CONFIG_HOME instead, when the app was started with that variable set). A vector.json or vector.jsonc you write in its own config folder, ~/Library/Application Support/ai.vector.app/config/vector/ on macOS, %APPDATA%\ai.vector.app\config\vector\ on Windows and ~/.config/ai.vector.app/config/vector/ on Linux, is read after the one Settings save to, so where both set a key, yours wins.
Every repository, in the terminal
The terminal reads ~/.config/vector/vector.json (%USERPROFILE%\.config\vector\vector.json on Windows) instead, so a setting there does not reach the desktop app.
Both
~/.vector/vector.json (%USERPROFILE%\.vector\vector.json on Windows) is read by the desktop app and the terminal alike.

Vector merges every file it reads. Objects such as provider, mcp, agent and command combine entry by entry, so each file can add entries of its own, and the instructions of every file add up. A company can also set a policy that overrides your own and a repository's settings and can lock keys; see For companies.

Values from the environment and from files

Anywhere in a settings file, {env:NAME} becomes the value of the environment variable NAME, or nothing when it is not set, and {file:path} becomes the contents of that file, trimmed. A relative path starts from the settings file's folder, and one starting with ~/ from your home folder. A {file:} that names a missing file is an error in that settings file. Use them to keep keys and long prompts out of the file: 

{
  "provider": {
    "gateway": {
      "options": {
        "baseURL": "https://llm.example.com/v1",
        "apiKey": "{env:GATEWAY_API_KEY}"
      }
    }
  },
  "agent": {
    "sql-review": {
      "description": "Reviews SQL migrations",
      "mode": "subagent",
      "prompt": "{file:./prompts/sql-review.md}"
    }
  }
}

In a repository you have not trusted, Vector leaves both as written and reads neither. MCP servers can also name a credential from Vector's own store with {vault:NAME}; see MCP servers in vector.json.

Before you trust a repository

Until you trust a repository, Vector ignores the keys in its settings that could run code or send your work somewhere else: provider, model, mcp, plugin, agent, command, instructions, skills, formatter, lsp and shell among them. It still applies what only narrows Vector, such as deny rules and disabled_providers. See Repository trust.

Keys and where they are described

enabled_providers and disabled_providers
Allow and block providers.
plugin
Plugins.
agent and default_agent
Custom agents.
skills
skills.paths and skills.urls, under Skills.
instructions
Instruction files.
permission
Permissions.
local
Vector Local, read only from your own settings and your company's policy.