Continue Configuration File Format: The Complete Guide to config.yaml

Continue expects a YAML-based configuration file named config.yaml that is validated against a strict JSON Schema generated from Zod definitions in the @continuedev/config-yaml package.

The Continue project (continuedev/continue) uses a structured YAML format to define LLM providers, assistants, and runtime behavior. Understanding the expected configuration file format for Continue is essential for customizing model providers, setting up organizational policies, and managing secrets securely.

File Location and Naming Convention

Default Location and Naming

The configuration file must be named config.yaml or config.yml. By default, Continue searches for this file at the repository root. The file is parsed by the ConfigYaml.load() method in packages/config-yaml/src/load/merge.ts, which handles file reading, include directive expansion, and initial validation.

Custom Paths via CLI

You can specify an alternative path using the --config flag:

continue --config ./my-config.yaml chat "Write a unit test for this function"

This flexibility allows you to maintain multiple configuration profiles for different environments or projects without renaming files.

Top-Level Configuration Sections

The config.yaml schema defines a hierarchy of top-level sections that configure the core agent, model providers, tools, and UI behavior. According to the schema defined in packages/config-yaml/src/schemas/index.ts, the following sections are recognized:

• models – Declares one or more LLM providers (OpenAI, Anthropic, Azure, etc.) with keys like provider, model, apiKey, apiBase, temperature, maxTokens, and requestOptions.
• assistants – Defines agents that can be invoked from the UI, including name, description, prompt, completionOptions, tools, and model references.
• policy – Organization-wide policy settings for self-hosted MCP servers, including disableTelemetry, allowedDomains, and maxFileSize.
• ui – UI customizations such as theme, fontSize, shortcut, and sidebar configuration.
• debug – Debug and logging controls like logLevel, trace, and showStackTraces.
• env – Secret-placeholder handling where ${ENV_VAR} strings are resolved from the environment at load time.
• metadata – Arbitrary free-form data that the SDK can expose to extensions.

Only keys defined in the schema are accepted. The schema is versioned under schema: "0.2.0" (see packages/config-yaml/src/schemas/data/*/v0.2.0.ts).

Validation and Schema Processing

The Validation Pipeline

When Continue loads a configuration, it executes a four-stage validation pipeline defined in the source code:

1. File Loading – ConfigYaml.load() reads the file, expands any !include directives, and merges package-level config fragments.
2. Unrolling – The unroller in packages/config-yaml/src/load/unroll.ts recursively imports any packages listed in the extends field and merges them into a single configuration tree.
3. Schema Validation – The resulting object is validated against configYamlSchema in packages/config-yaml/src/schemas/index.ts. Errors are surfaced as human-readable messages.
4. Secret Injection – Placeholders like ${OPENAI_API_KEY} are replaced with actual environment values, unless the placeholder appears inside a secret field, in which case it is stored as a secret reference.

Because validation is performed on import, malformed YAML or unknown keys will stop the extension from starting, preventing runtime crashes.

Environment Variables and Secret Management

Never hard-code secret values in your configuration files. Instead, use the ${ENV_VAR} syntax:

models:
  - provider: openai
    model: gpt-4o-mini
    apiKey: ${OPENAI_API_KEY}
    temperature: 0.7

The loader sources these values securely from the process environment at runtime. This approach ensures that sensitive credentials remain outside version control while remaining accessible to the application.

Practical Configuration Examples

Minimal Configuration

A basic config.yaml requires only a model definition and an assistant:

models:
  - provider: openai
    model: gpt-4o-mini
    apiKey: ${OPENAI_API_KEY}
    temperature: 0.7

assistants:
  - name: default
    description: "General purpose assistant"
    prompt: |
      You are an AI helping the user with coding tasks.
    model: openai/gpt-4o-mini

Multiple Providers and Custom Tools

Configure multiple LLM providers and define assistants with specific tool access:

models:
  - provider: anthropic
    model: claude-3-5-sonnet
    apiKey: ${ANTHROPIC_API_KEY}
  - provider: azure
    model: azure-gpt-35-turbo
    apiBase: https://my-azure-openai.openai.azure.com/
    apiKey: ${AZURE_OPENAI_KEY}
    requestOptions:
      deploymentId: my-deployment

assistants:
  - name: code-helper
    description: "Helps write and refactor code"
    model: anthropic/claude-3-5-sonnet
    tools:
      - name: fileSearch
        description: "Searches files in the workspace"
        parameters:
          type: object
          properties:
            query:
              type: string
          required: [query]

Loading Configurations Programmatically

Use the TypeScript SDK to load and validate configurations directly:

import { Continue } from "@continuedev/continue-sdk";
import { readFileSync } from "fs";

const yaml = readFileSync("config.yaml", "utf8");
const continueClient = await Continue.fromConfig(yaml);

await continueClient.ask("Explain the difference between async/await and promises.");

This approach instantiates a Continue client from packages/continue-sdk/typescript/src/Continue.ts using your validated configuration.

Summary

• Continue requires a YAML configuration file named config.yaml (or config.yml) located at the repository root or specified via the --config CLI flag.
• The configuration is validated against a strict JSON Schema generated from Zod definitions in packages/config-yaml/src/schemas/index.ts.
• Top-level sections include models, assistants, policy, ui, debug, env, and metadata.
• Environment variable substitution using ${ENV_VAR} syntax keeps secrets secure by sourcing them from the runtime environment.
• The validation pipeline in @continuedev/config-yaml prevents runtime crashes by catching schema violations at load time.

Frequently Asked Questions

What is the exact filename required for Continue configuration?

The expected file name is config.yaml or config.yml. While the default location is the repository root, you can pass a custom path using the --config flag when running the Continue CLI.

How does Continue handle environment variables in config.yaml?

Continue uses the ${ENV_VAR} syntax for environment variable substitution. During the Secret Injection phase of validation, the loader replaces these placeholders with actual values from the process environment. This prevents sensitive credentials from being stored in plain text within the configuration file.

What happens if I include invalid keys in my configuration?

If you include keys not defined in the schema, the validation will fail during the Schema Validation step in packages/config-yaml/src/schemas/index.ts. The extension will not start, and you will receive human-readable error messages describing the validation failures. Extra fields are ignored unless strict mode is enabled, which may cause additional errors.

Can I split my configuration across multiple files?

Yes. The !include directive and the extends field allow you to modularize your configuration. The unroller in packages/config-yaml/src/load/unroll.ts recursively imports packages listed in extends and merges them into a single configuration tree before validation occurs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}