Configuration Guide

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.

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

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.

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):

COMIS_CONFIG_PATHS="/etc/comis/base.yaml:/etc/comis/overrides.yaml"

Later files override values from earlier ones.

Minimal working config

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

agents:
  default:
    name: "Atlas"
    provider: "anthropic"
    model: "claude-sonnet-4-5-20250929"

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.

Required: Agent configuration

Required: You must configure at least one agent with a name, provider, and model.

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"`

Anthropic
OpenAI
Google
Ollama (local)

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.

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.

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.

agents:
  default:
    name: "Atlas"
    provider: "ollama"
    model: "llama3"

No API key needed. Make sure Ollama is running locally on its default port.

Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

Recommended: Gateway

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

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)

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.

Recommended: Channels

Channels connect your agent to messaging platforms like Telegram, Discord, and Slack.

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

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.

Each platform has different settings. See the Channels section for step-by-step setup guides for all supported platforms.

Optional: Common settings

These settings have sensible defaults. Change them only when you need to.

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.

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.

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.

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:

agents:
  default:
    secrets:
      allow:
        - "ANTHROPIC_API_KEY"
        - "GITHUB_*"

Common static-key providers use these names. See Environment Variables 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.

Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

$include directive

Split your config into multiple files for organization:

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:

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:

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.

~/.comis/config.yaml

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"

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 for details.

See Config Reference 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.

For the complete reference of all configuration sections, see Config YAML Reference.

Next steps

Verify Installation

Run diagnostic commands to confirm everything is working.

Connect a Channel

Step-by-step guides for Telegram, Discord, Slack, and more.

Security

Understand the security protections built into Comis.

Config Reference

Complete reference for all 41 configuration sections.

​Where config lives

​Minimal working config

​Required: Agent configuration

​Recommended: Gateway

​Recommended: Channels

​Optional: Common settings

​Secrets and API keys

​$include directive

​Validate your config

​Context engine

​Advanced configuration

​Next steps

Verify Installation

Connect a Channel

Security

Config Reference

Where config lives

Minimal working config

Required: Agent configuration

Recommended: Gateway

Recommended: Channels

Optional: Common settings

Secrets and API keys

$include directive

Validate your config

Context engine

Advanced configuration

Next steps