/ docs

Configuration

Project config, user config, API keys, and template overrides.

Configuration layers

Layer Location Committed to git? Purpose Status
User config ~/.vibeconfig No API keys, personal defaults Implemented
Inline Vibefile Yes Model selection, per-target overrides Implemented
Project config .vibe/config.yaml Yes MCP server definitions, skill sources Implemented

User configuration — ~/.vibeconfig

The user config file holds API keys and personal defaults. It is never committed to version control.

API key resolution order (implemented):

  1. --api-key CLI flag
  2. VIBE_API_KEY environment variable
  3. Provider-specific env var (inferred from the model):
    • ANTHROPIC_API_KEY for Claude models
    • OPENAI_API_KEY for OpenAI models
  4. ~/.vibeconfig global config file
# ~/.vibeconfig — never committed to version control
default_model: claude-sonnet-4-6
anthropic_key: sk-ant-...
openai_key: sk-...

The CLI supports both Anthropic (Claude) and OpenAI models. The provider is automatically detected from the model name — claude/sonnet/haiku/opus routes to Anthropic, gpt/o1/o3 routes to OpenAI.

Inline configuration — Vibefile

Model selection is declared directly in the Vibefile:

model = claude-sonnet-4-6

deploy:
    "deploy to production"

Individual targets can override the top-level model:

model = claude-haiku-4-5

release: test build
    model = claude-opus-4-6
    "bump version, update changelog, tag, push, open release PR"

Template overrides

The vibe init template system supports overrides. When resolving a template for a detected language, the CLI checks these locations in order:

  1. .vibe/templates/<lang>.yaml — project-local override
  2. ~/.vibe/templates/<lang>.yaml — user-global override
  3. Built-in templates — always available as fallback

This means you can customize the targets generated by vibe init for your project or globally for all your projects without modifying the CLI source. See Project Detection for the template YAML format.

Project configuration — .vibe/config.yaml

The project config lives at .vibe/config.yaml and is committed to version control. It never contains secrets — those belong in ~/.vibeconfig or environment variables.

# .vibe/config.yaml
servers:
  fly-mcp:
    url: https://mcp.fly.io/sse
  postgres-mcp:
    command: npx @modelcontextprotocol/server-postgres
    args: ["--connection-string", "postgresql://localhost/mydb"]

skill_sources:
  - ./skills
  - ~/.vibe/skills

registry:
  url: https://aregistry.ai

Fields

Field Description
servers MCP server definitions (URL-based or local command). Used by agent-mode targets with @mcp.
skill_sources Additional directories to search for skills. The CLI always checks skills/, .vibe/skills/, and ~/.vibe/skills/ — these are extra paths. Supports ~/ expansion.
registry Registry URL for dynamic server/skill resolution.

If the file doesn’t exist, the CLI uses empty defaults — everything works, you just don’t get MCP servers or extra skill sources.

Registry integration

Coming soon.

Previous ← Failure Handling Next Directives →