Configuration Reference

Copair is configured through YAML files at two levels:

Global: ~/.copair/config.yaml — applies to all projects
Project: .copair/config.yaml — overrides for the current project

Project settings take precedence over global settings. Both files use the same schema.

Complete Example

# ~/.copair/config.yaml
version: 1
default_model: claude-sonnet

providers:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    models:
      claude-sonnet:
        id: claude-sonnet-4-20250514
      claude-opus:
        id: claude-opus-4-20250514

  openai:
    api_key: "${OPENAI_API_KEY}"
    models:
      gpt-5:
        id: gpt-5

  ollama:
    type: openai-compatible
    base_url: http://localhost:11434/v1
    models:
      llama4:
        id: llama4
        supports_tool_calling: false

identity:
  name: Copair
  email: "copair[bot]@noreply.dugleelabs.io"

permissions:
  mode: ask
  allow_commands:
    - git status
    - git diff
    - npm test

context:
  summarization_model: qwen-7b
  max_sessions: 1

knowledge:
  warn_size_kb: 8
  max_size_kb: 16

ui:
  status_bar: true
  syntax_highlight: true
  bordered_input: true
  output_collapsing: true
  vi_mode: false
  suggestions: true
  tab_completion: true

security:
  path_validation: strict
  redact_high_entropy: false

network:
  web_search_timeout_ms: 15000
  provider_timeout_ms: 120000

mcp_servers: []

Providers

Configure one or more AI providers. Each provider contains a models map where keys are aliases you use to reference models:

providers:
  <name>:
    api_key: "${ENV_VAR}"           # API key (env var reference)
    base_url: "https://..."         # API endpoint (optional, auto-detected for known providers)
    type: openai-compatible         # Required for non-standard providers (Ollama, vLLM, etc.)
    models:
      <alias>:                      # User-friendly name (used with /model and default_model)
        id: "model-id"             # Provider's actual model ID
        max_tokens: 8192           # Max output tokens (optional)
        context_window: 200000     # Max input context (optional)
        supports_tool_calling: true # Native tool calling support (optional)
        supports_streaming: true    # Streaming response support (optional)

Field	Type	Required	Description
`api_key`	string	No*	API key or env var reference. Not required for local providers (Ollama, vLLM).
`base_url`	string	No	Custom API endpoint URL. Defaults to the provider's official endpoint.
`type`	string	No*	Provider type: `anthropic`, `openai`, `google`, or `openai-compatible`. Auto-detected from the provider name for `anthropic`, `openai`, and `google`/`gemini`. Required for custom providers.
`models`	object	Yes	Map of model aliases to model configurations.

Environment variables are resolved lazily — only when the provider is actually used. Missing env vars for unused providers do not cause errors.

Top-Level Defaults

version: 1                    # Required
default_model: claude-sonnet  # Model alias (must match a key in a provider's models map)

Identity

Configure the co-author identity for git commits:

identity:
  name: "Copair"
  email: "copair[bot]@noreply.dugleelabs.io"

Field	Type	Default	Description
`name`	string	`Copair`	Name used in `Co-authored-by:` trailers
`email`	string	`copair[bot]@noreply.dugleelabs.io`	Email used in `Co-authored-by:` trailers

To link the co-author to a real GitHub profile, use a GitHub noreply email: [email protected].

Permissions

permissions:
  mode: ask                   # ask | auto-approve | deny
  allow_commands:             # Bash commands auto-approved (no shell operators)
    - git status
    - git diff
    - npm test
  allow_paths:                # Glob patterns for paths outside the project root
    - ~/shared-libs
  deny_paths:                 # Glob patterns unconditionally denied
    - ~/.ssh
    - ~/.aws

Field	Type	Default	Description
`mode`	string	`ask`	Default permission mode for tool calls
`allow_commands`	string[]	`[]`	Bash commands that are auto-approved without prompting. Shell operators (`;`, `&&`, `\|`) are not allowed.
`allow_paths`	string[]	`[]`	Glob patterns of paths outside the project root that the agent may access.
`deny_paths`	string[]	`[]`	Glob patterns unconditionally denied regardless of approval mode. When non-empty, replaces the built-in deny list.

See Permissions & Approval for allow-list configuration.

Context

context:
  summarization_model: "ollama/llama4"
  max_sessions: 1

Field	Type	Default	Description
`summarization_model`	string	auto	Model used for session summarization on exit. Defaults to local 7B via Ollama if available, else the active model.
`max_sessions`	number	`1`	Maximum sessions to retain per project. Oldest sessions are pruned when exceeded.

UI

Toggle visual features:

ui:
  status_bar: true
  syntax_highlight: true
  bordered_input: true
  output_collapsing: true
  vi_mode: false

Field	Type	Default	Description
`status_bar`	boolean	`true`	Show persistent status bar at terminal bottom
`syntax_highlight`	boolean	`true`	Syntax highlighting in code blocks
`bordered_input`	boolean	`true`	Bordered input box (auto-disabled in terminals with ghosting issues)
`output_collapsing`	boolean	`true`	Collapse consecutive same-tool calls into a single updating line
`vi_mode`	boolean	`false`	Enable vi keybindings in the input line

Knowledge

Configure the project knowledge base (COPAIR_KNOWLEDGE.md):

knowledge:
  warn_size_kb: 8
  max_size_kb: 16

Field	Type	Default	Description
`warn_size_kb`	number	`8`	Warn when `COPAIR_KNOWLEDGE.md` exceeds this size in KB
`max_size_kb`	number	`16`	Hard cap in KB — entries are auto-pruned beyond this

Security

Control file system access and secrets handling:

security:
  path_validation: strict     # 'strict' (default) or 'warn'
  redact_high_entropy: false  # opt-in high-entropy base64 redaction

Field	Type	Default	Description
`path_validation`	`strict` \| `warn`	`strict`	In `strict` mode, file tool calls outside the project root are denied. In `warn` mode, they are logged and allowed — useful for debugging path issues.
`redact_high_entropy`	boolean	`false`	When `true`, long high-entropy base64 strings are also redacted from logs and tool results, in addition to the known secret patterns.

In strict mode (default), the read, write, edit, glob, and grep tools are restricted to paths within the project root (resolved via git rev-parse --show-toplevel, or the directory where copair was started). Symlinks are resolved before the boundary check — symlink escape attempts are denied.

Network

Configure timeouts for outbound network calls:

network:
  web_search_timeout_ms: 15000    # default: 15s
  provider_timeout_ms: 120000     # default: 120s

Field	Type	Default	Description
`web_search_timeout_ms`	number	`15000`	Timeout in milliseconds for web search adapter fetch calls.
`provider_timeout_ms`	number	`120000`	Timeout in milliseconds passed to the LLM provider client (Anthropic, OpenAI).

MCP

mcp_servers:
  - name: "server-name"
    command: "npx"
    args: ["@scope/mcp-server"]
    env:
      KEY: "${ENV_VAR}"
    timeout_ms: 30000  # optional — overrides global 30s default for this server

Field	Type	Default	Description
`name`	string	required	Identifier for this server, used in allow-list rules and logs.
`command`	string	required	Command to start the server process.
`args`	string[]	`[]`	Arguments passed to the command.
`env`	object	—	Environment variables injected into the server process. Supports `${VAR}` references.
`timeout_ms`	number	`30000`	Tool call timeout for this server in milliseconds. If the server does not respond within this window, it is marked degraded and subsequent calls fail immediately.

See MCP Servers for full MCP configuration.

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables anywhere in config:

apiKey: "${ANTHROPIC_API_KEY}"

Variables are resolved at the time the value is accessed, not when the config file is loaded. This means you can configure multiple providers and only need the environment variables for the providers you actually use.

Next Steps

Getting Started — Quick setup with your first provider
Permissions & Approval — Allow-list YAML format