> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Guide

> Set up your config.yaml with required settings, channels, and customization

Comis uses a single YAML file for configuration. If you used the setup wizard
(`comis init`), it already created a working config. This guide explains what is
in that file and how to customize it.

<Info>
  You don't need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.
</Info>

## Where config lives

| Setting        | Value                                                                    |
| -------------- | ------------------------------------------------------------------------ |
| Default path   | `~/.comis/config.yaml`                                                   |
| Custom path    | Set `COMIS_CONFIG_PATHS=/path/to/config.yaml`                            |
| Multiple files | Colon-separated paths -- later files override earlier ones               |
| Reload         | Config is loaded once at startup. Restart the daemon to pick up changes. |

<Info>
  When you set `COMIS_CONFIG_PATHS`, Comis reads config from that path instead of
  the default. You can point to multiple files using colon-separated paths
  (same convention as `PATH`):

  ```bash theme={}
  COMIS_CONFIG_PATHS="/etc/comis/base.yaml:/etc/comis/overrides.yaml"
  ```

  Later files override values from earlier ones.
</Info>

## Minimal working config

This is a minimal agent definition. It still needs a usable credential, OAuth
profile, or local provider:

```yaml theme={}
agents:
  default:
    name: "Atlas"
    provider: "anthropic"
    model: "claude-sonnet-4-5-20250929"
```

<Info>
  The schema supplies defaults for the other sections. Logging defaults to
  `debug`; the gateway defaults to loopback port `4766`; local state uses SQLite.
  Credentials are resolved through `SecretManager`, whose default writable
  backend is the encrypted store.
</Info>

## Required: Agent configuration

<Warning>
  **Required:** You must configure at least one agent with a name, provider, and model.
</Warning>

Every agent needs three fields:

| Field      | Description                      | Example                        |
| ---------- | -------------------------------- | ------------------------------ |
| `name`     | Display name for the agent       | `"Atlas"`                      |
| `provider` | AI provider identifier           | `"anthropic"`                  |
| `model`    | Model to use (provider-specific) | `"claude-sonnet-4-5-20250929"` |

<Tabs>
  <Tab title="Anthropic">
    ```yaml theme={}
    agents:
      default:
        name: "Atlas"
        provider: "anthropic"
        model: "claude-sonnet-4-5-20250929"
    ```

    Store the credential with `comis secrets set ANTHROPIC_API_KEY`, or provide
    it through a protected environment variable.
  </Tab>

  <Tab title="OpenAI">
    ```yaml theme={}
    agents:
      default:
        name: "Atlas"
        provider: "openai"
        model: "gpt-4o"
    ```

    Store the credential with `comis secrets set OPENAI_API_KEY`, or provide it
    through a protected environment variable.
  </Tab>

  <Tab title="Google">
    ```yaml theme={}
    agents:
      default:
        name: "Atlas"
        provider: "google"
        model: "gemini-2.0-flash"
    ```

    Store the credential with `comis secrets set GOOGLE_API_KEY`, or provide it
    through a protected environment variable.
  </Tab>

  <Tab title="Ollama (local)">
    ```yaml theme={}
    agents:
      default:
        name: "Atlas"
        provider: "ollama"
        model: "llama3"
    ```

    No API key needed. Make sure Ollama is running locally on its default port.
  </Tab>
</Tabs>

<Warning>
  Never store API keys, tokens, or passwords directly in `config.yaml`. Use the `.env` file or [Secret Manager](/security/secrets) for credential management.
</Warning>

## Recommended: Gateway

<Tip>
  The gateway enables the web dashboard and API access. It is enabled by default,
  but you can customize its settings.
</Tip>

```yaml theme={}
gateway:
  enabled: true
  host: "127.0.0.1"
  port: 4766
  tokens:
    - id: "default"
      secret: "${COMIS_GATEWAY_TOKEN}"
      scopes: ["*"]
```

| Field     | Default       | Description                                                     |
| --------- | ------------- | --------------------------------------------------------------- |
| `enabled` | `true`        | Enable or disable the gateway server                            |
| `host`    | `"127.0.0.1"` | Bind address. Use `"0.0.0.0"` for external access or Docker.    |
| `port`    | `4766`        | Port for the web dashboard and API                              |
| `tokens`  | `[]`          | Bearer tokens for API authentication (optional but recommended) |

<Info>
  The `tokens` section is optional. Without it, the gateway accepts unauthenticated
  requests on localhost. Add a token when you expose the gateway to a network.
</Info>

## Recommended: Channels

<Tip>
  Channels connect your agent to messaging platforms like Telegram, Discord, and Slack.
</Tip>

Here is an example with Telegram -- the simplest channel to configure:

```yaml theme={}
channels:
  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
```

Store `TELEGRAM_BOT_TOKEN` with `comis secrets set TELEGRAM_BOT_TOKEN`, or
provide it through a protected environment variable, using the token from
[@BotFather](https://t.me/BotFather).

<Info>
  Each platform has different settings. See the [Channels](/channels/index) section
  for step-by-step setup guides for all supported platforms.
</Info>

## Optional: Common settings

<Info>
  These settings have sensible defaults. Change them only when you need to.
</Info>

```yaml theme={}
logLevel: "debug"
dataDir: "~/.comis"
tenantId: "default"
```

| Setting    | Default      | Description                                                                            |
| ---------- | ------------ | -------------------------------------------------------------------------------------- |
| `logLevel` | `"debug"`    | Log verbosity. Options: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"fatal"` |
| `dataDir`  | `"~/.comis"` | Base directory for databases, logs, and models                                         |
| `tenantId` | `"default"`  | Default logical scope attached to tenant-aware requests and stored records.            |

<Warning>
  `tenantId` and agent IDs provide logical routing and storage scope inside one
  trusted Comis deployment. They do not create separate processes, filesystems,
  daemon accounts, or host boundaries for mutually hostile tenants. Use separate
  deployments when you require process or host isolation.
</Warning>

## Secrets and API keys

Comis resolves `${VAR_NAME}` references through `SecretManager`. New wizard
setups use `security.storage: encrypted`, place credential ciphertext in
`~/.comis/secrets.db`, and keep `SECRETS_MASTER_KEY` in the owner-readable
`~/.comis/.env` file. Back up that key separately; losing it makes the database
unrecoverable.

Plain environment variables and the `file` storage mode are explicit
alternatives. They do not provide the encrypted store's at-rest protection.

<Warning>
  Per-agent secret access is unrestricted unless you configure a **non-empty**
  `agents.<id>.secrets.allow` list. An omitted or empty list means the agent's
  scoped secret manager may resolve every secret available through the base
  manager; it does not mean "deny all." Configure explicit glob patterns for
  least privilege:

  ```yaml theme={}
  agents:
    default:
      secrets:
        allow:
          - "ANTHROPIC_API_KEY"
          - "GITHUB_*"
  ```
</Warning>

Common static-key providers use these names. See [Environment Variables](/reference/environment-variables#llm-provider-keys) for the complete catalog, aliases, and multi-value provider requirements.

| Provider    | Environment Variable |
| ----------- | -------------------- |
| Anthropic   | `ANTHROPIC_API_KEY`  |
| OpenAI      | `OPENAI_API_KEY`     |
| Google      | `GOOGLE_API_KEY`     |
| Groq        | `GROQ_API_KEY`       |
| Mistral     | `MISTRAL_API_KEY`    |
| DeepSeek    | `DEEPSEEK_API_KEY`   |
| xAI         | `XAI_API_KEY`        |
| Together AI | `TOGETHER_API_KEY`   |
| Cerebras    | `CEREBRAS_API_KEY`   |
| OpenRouter  | `OPENROUTER_API_KEY` |
| Ollama      | Not needed           |

The wizard initializes encrypted storage automatically. For a manual setup, run
`comis secrets init`, back up the generated master key, then add values with
`comis secrets set <NAME>`. See [Secrets Management](/security/secrets).

<Warning>
  Never store API keys, tokens, or passwords directly in `config.yaml`. Use the `.env` file or [Secret Manager](/security/secrets) for credential management.
</Warning>

## \$include directive

Split your config into multiple files for organization:

```yaml theme={}
channels:
  $include: channels.yaml
```

The included file path is relative to the file that contains the `$include`
directive. This is useful for separating channel credentials from the main
config or sharing a base config across environments.

## Validate your config

Check your config file for syntax errors and missing fields:

```bash theme={}
comis config validate
```

Expected output for a valid config:

```
Configuration is valid
```

If there are errors, you will see the specific field and issue:

```
Configuration error:
  agents.default.provider: Expected string, received number
```

To see the fully resolved config with all defaults filled in:

```bash theme={}
comis config show
```

## Context engine

The context engine manages what your agent sees each turn. The default mode is
DAG. Most users do not need to change any context engine settings -- the
defaults work well.

```yaml title="~/.comis/config.yaml" theme={}
agents:
  default:
    contextEngine:
      enabled: true
      # version: "dag"  # This is the default; set "pipeline" for the simpler engine
      thinkingKeepTurns: 10
      historyTurns: 15
      observationKeepWindow: 25
      observationTriggerChars: 120000
      compactionCooldownTurns: 5
      compactionModel: "anthropic:claude-haiku-4-5-20250929"
```

<Note>
  The DAG mode (the `dag` engine version) is the **default**: `version`
  defaults to `"dag"` (set `"pipeline"` to opt into the simpler engine).
  Canonical messages and tool results remain recoverable, but the active model
  prompt is still token-budgeted. It keeps a verbatim fresh tail and represents
  older regions with selected raw steps or explicitly lossy summaries. The
  in-session `ctx_*` tools recover underlying detail on demand; they do not put
  the full canonical transcript into every provider call. See
  [Compaction](/agents/compaction) for details.
</Note>

See [Config Reference](/reference/config-yaml) for the complete list of all 27
context engine fields.

## Advanced configuration

The config schema supports 41 top-level sections. This guide covered the
essential ones. The remaining sections control memory, security, routing,
scheduling, monitoring, plugins, and more.

<Info>
  For the complete reference of all configuration sections, see
  [Config YAML Reference](/reference/config-yaml).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Verify Installation" icon="circle-check" href="/installation/verify">
    Run diagnostic commands to confirm everything is working.
  </Card>

  <Card title="Connect a Channel" icon="messages" href="/channels/index">
    Step-by-step guides for Telegram, Discord, Slack, and more.
  </Card>

  <Card title="Security" icon="shield-check" href="/get-started/security">
    Understand the security protections built into Comis.
  </Card>

  <Card title="Config Reference" icon="book" href="/reference/config-yaml">
    Complete reference for all 41 configuration sections.
  </Card>
</CardGroup>