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.

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 the absolute minimum YAML that produces a working agent:

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

Everything else has sensible defaults. The gateway starts automatically on port 4766, logging is set to info level, and memory uses a local SQLite database. The API key is read from the .env file in your data directory — see Secrets and API Keys below.

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

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

Set ANTHROPIC_API_KEY in your .env file.

OpenAI

agents:
  default:
    name: "Atlas"
    provider: "openai"
    model: "gpt-4o"

Set OPENAI_API_KEY in your .env file.

Google

agents:
  default:
    name: "Atlas"
    provider: "google"
    model: "gemini-2.0-flash"

Set GOOGLE_API_KEY in your .env file.

Ollama (local)

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

Set TELEGRAM_BOT_TOKEN in your .env file with 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"	Isolates data between environments. Change when running multiple instances.

Secrets and API keys

Comis resolves ${VAR_NAME} references in config values from environment variables or from the .env file in your data directory (~/.comis/.env by default).

The setup wizard generates config with ${VAR} references and puts the actual values in .env. Here is a typical .env file:

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC...
COMIS_GATEWAY_TOKEN=your-gateway-secret-at-least-32-characters-long

Each provider has a standard environment variable name:

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

For encrypted secret storage, run comis secrets init to set up the secrets vault. See Secrets Management for details.

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 pipeline. 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) — the v2.12 “Lossless Context DAG” lossless engine — is the default: version defaults to "dag" (set "pipeline" to opt into the simpler engine). DAG keeps the full faithful history losslessly (a verbatim fresh tail + transcript repair), zoomably compresses the oldest history under a token budget, and exposes the in-session ctx_* expansion tools. 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.