Configuration

Duragent is configured via duragent.yaml (server-level) and agent.yaml (per-agent). This page covers server configuration; for agent configuration see Agent Format.

Environment Variable Interpolation

Configuration files support shell-style environment variable expansion:

Environment Variables

Duragent reads certain environment variables directly at startup, independent of config file interpolation.

LLM Provider Keys

These are read directly from the environment — there is no YAML config equivalent. Anthropic also supports OAuth login via duragent login anthropic, which stores credentials at ~/.duragent/auth.json and takes precedence over the environment variable. See Authentication for details.

At least one LLM provider must be configured for agents to function.

Tool Keys

These are read directly from the environment — there is no YAML config equivalent.

Gateway Tokens

Gateway tokens are handled differently depending on how you run the gateway:

• In-process (compiled-in feature): the token comes from the bot_token field in duragent.yaml, which supports ${VAR} interpolation.
• Standalone binary: the token is read directly from the environment variable below.

These are separate code paths — they do not conflict.

Tip: When running gateways as external plugins (via gateways.external[]), you can forward these through the env field in duragent.yaml using ${VAR} interpolation instead of relying on the host environment.

duragent.yaml

Full Example

# Workspace root (default: .duragent)
# workspace: .duragent

# Server
server:
  host: 0.0.0.0
  port: 8080
  request_timeout_seconds: 300
  idle_timeout_seconds: 60
  keep_alive_interval_seconds: 15
  admin_token: ${ADMIN_TOKEN:-}
  api_token: ${API_TOKEN:-}

# Agent directory (optional, defaults to {workspace}/agents)
# agents_dir: .duragent/agents

# Services
services:
  session:
    # path: .duragent/sessions

# World memory
world_memory:
  # path: .duragent/memory/world

# Sessions
sessions:
  ttl_hours: 168
  compaction: discard

# Gateways
gateways:
  telegram:
    enabled: true
    bot_token: ${TELEGRAM_BOT_TOKEN}

  external:
    - name: discord
      command: /usr/local/bin/duragent-discord
      args: ["--verbose"]
      env:
        DISCORD_BOT_TOKEN: ${DISCORD_BOT_TOKEN}
      restart: on_failure

# Routes
routes:
  - match:
      gateway: telegram
      sender_id: "123456789"
    agent: personal-assistant

  - match:
      gateway: telegram
      chat_type: group
    agent: group-moderator

  - match: {}
    agent: default-assistant

# Sandbox
sandbox:
  mode: trust

Fields Reference

Server

Workspace

Sessions

Gateways

Routes

Match conditions:

Routes are evaluated top-to-bottom; first match wins. An empty match: {} acts as a catch-all.

Sandbox

Path Resolution

All relative paths are resolved relative to the config file directory, not the current working directory. When optional path fields are omitted, they default to subdirectories of the workspace.

Context Window Management

Context window settings are configured per-agent in agent.yaml under spec.session.context. See Agent Format > session.context for details.

Duragent automatically detects context window sizes from model names when max_input_tokens is not set. Supported model families include Claude, GPT-4/5, Gemini, Grok, DeepSeek, Qwen, Llama, and Mistral.