Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bolt-builder/bolt-cli/llms.txt

Use this file to discover all available pages before exploring further.

Bolt uses a JSON with Comments (.jsonc) file for project and global configuration. The schema is versioned and published at https://opencode.ai/config.json, which editors can use to provide autocompletion and validation.

​
Config file locations

Bolt merges configuration from two locations. Per-project settings win over global settings when the same key appears in both.
ScopePath
Per-project.bolt/bolt.jsonc (or .bolt/bolt.json) in your project root
Globalbolt.jsonc (or bolt.json) in your OS config directory
The OS config directory is:
  • macOS: ~/Library/Application Support/bolt/
  • Linux: ~/.config/bolt/
  • Windows: %APPDATA%\bolt\
Bolt also reads legacy opencode.jsonc / opencode.json files in the same locations. New projects should use the bolt.jsonc naming convention, which takes priority over the legacy filenames.
Bolt creates a minimal global config file with the $schema line on first run, and creates .bolt/bolt.jsonc in your project root the first time you open the TUI in that directory.

​
Schema fields

​
$schema
string
URL pointing to the JSON schema for this config file. Enables autocompletion and inline validation in editors that support JSON Schema (VS Code, Zed, JetBrains IDEs, etc.).
"$schema": "https://opencode.ai/config.json"
​
model
string
Default model for all sessions, expressed as provider/model. This can be overridden per-session with bolt run --model or in the TUI model picker.
"model": "anthropic/claude-opus-4-5"
Run bolt models to see all available provider/model strings for your configured providers.
​
provider
object
Provider-specific credential and settings overrides. Each key is a provider ID (e.g. anthropic, openai, google). The most common use is to set an API key via an environment variable reference so that the key is never stored in plaintext.
"provider": {
  "anthropic": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "openai": {
    "apiKey": "${OPENAI_API_KEY}"
  }
}
Values that start with ${ and end with } are treated as environment variable references and expanded at runtime.
​
mcp
object
MCP server configurations, keyed by a name you choose. Bolt supports two server types:Remote server — connects over HTTP/SSE, with optional OAuth:
"mcp": {
  "my-remote-tools": {
    "type": "remote",
    "url": "https://mcp.example.com/tools",
    "oauth": {}
  }
}
FieldTypeDescription
type"remote"Identifies this as a remote HTTP server
urlstringFull URL of the MCP endpoint
oauthobject | falseOAuth configuration object (with optional clientId, clientSecret, scope, redirectUri). Set to false to disable OAuth auto-detection.
headersobjectHTTP headers to send with every request ({ "Key": "Value" })
enabledbooleanEnable or disable this server on startup
timeoutnumberRequest timeout in milliseconds (default: 5000)
Local server — spawns a subprocess over stdio:
"mcp": {
  "filesystem": {
    "type": "local",
    "command": ["npx", "@modelcontextprotocol/server-filesystem", "/tmp"],
    "environment": {
      "DEBUG": "1"
    }
  }
}
FieldTypeDescription
type"local"Identifies this as a local stdio server
commandstring[]Command and all arguments to spawn
cwdstringWorking directory for the server process (relative paths resolve from the workspace directory)
environmentobjectExtra environment variables to pass to the subprocess
enabledbooleanEnable or disable this server on startup
timeoutnumberRequest timeout in milliseconds (default: 5000)
Use bolt mcp add for an interactive wizard, or bolt mcp list to inspect current server status.
​
instructions
string[]
Additional system instructions appended to every session in this project or globally. Instructions from multiple config files are merged (deduplicated). Use this to inject project-specific conventions, style rules, or constraints that every agent should follow.
"instructions": [
  "Always write tests for every new function.",
  "Use TypeScript strict mode. Never use `any`.",
  "Follow the repository's existing naming conventions."
]
​
plugin
string[]
Plugin specs to load. Each entry is an npm package name, a local file path, or a URL. Plugins can extend the TUI, add slash-commands, or register additional providers. Use bolt plugin install <spec> to install a plugin and have it added to this array automatically.
"plugin": [
  "@my-org/bolt-plugin-jira",
  "./local-plugins/my-custom-plugin.ts"
]

​
Complete example

The following .bolt/bolt.jsonc shows a realistic project configuration: 
{
  "$schema": "https://opencode.ai/config.json",

  // Default model for all sessions in this project
  "model": "anthropic/claude-opus-4-5",

  // Provider credentials — never hard-code keys; use env var references
  "provider": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  },

  // MCP servers available in this project
  "mcp": {
    // Remote server with OAuth
    "my-tools": {
      "type": "remote",
      "url": "https://mcp.example.com/tools",
      "oauth": {}
    },
    // Local stdio server
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  },

  // System instructions injected into every session
  "instructions": [
    "Always write tests for new functions.",
    "Use conventional commits for all commit messages.",
    "Prefer explicit error handling over broad try/catch blocks."
  ],

  // Plugins to load
  "plugin": [
    "@my-org/bolt-plugin-linear"
  ]
}
Run bolt debug config to see the fully-resolved configuration after all files are merged. This is the fastest way to confirm that your per-project and global configs are combining correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us