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

> Learn the config.yaml format for Continue AI. Understand the strict YAML validation against JSON Schema for seamless configuration. Get the complete guide.

- Repository: [Continue/continue](https://github.com/continuedev/continue)
- Tags: api-reference
- Published: 2026-06-18

---

**Continue expects a YAML-based configuration file named [`config.yaml`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/config.yaml)** or [`config.yml`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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:

```bash
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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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:

```yaml
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`](https://github.com/continuedev/continue/blob/main/config.yaml) requires only a model definition and an assistant:

```yaml
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:

```yaml
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:

```typescript
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`](https://github.com/continuedev/continue/blob/main/packages/continue-sdk/typescript/src/Continue.ts) using your validated configuration.

## Summary

- Continue requires a **YAML configuration file** named [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) (or [`config.yml`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/config.yaml)** or [`config.yml`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/src/load/unroll.ts) recursively imports packages listed in `extends` and merges them into a single configuration tree before validation occurs.