Configuration Guide

Learn how to configure your Capsule Agent using YAML configuration files and environment variables.

Configuration File

The primary configuration is done through agent.config.yaml, which should be mounted at /app/agent.config.yaml in the container. You can also override the path with AGENT_CONFIG_FILE.

Workspace Seed Files

You can copy files or directories into the agent workspace at startup:

workspaceFiles:
  - README.md
  - prompts/
  - scripts/setup.sh

Entries are resolved relative to the config directory (or AGENT_CONFIG_FILE path). They are copied into the workspace directory (default: /app/agent-workspace).

Basic Configuration

Agent Settings

agent:
  name: My Agent
  description: A helpful assistant for specific tasks

  # Model configuration
  model:
    name: openai/gpt-5-mini
    parameters:
      temperature: 0.7
      max_tokens: 4000

  # Built-in tools
  tools:
    exec:
      enabled: true
    memory:
      enabled: false
    read_file:
      enabled: true
    grep_files:
      enabled: true
    edit_file:
      enabled: true

  # Built-in prompts
  builtInPrompts:
    enabled: true

Model Options

Supported AI providers and models:

OpenAI:

model:
  name: openai/gpt-5-mini
  # or: openai/gpt-5

Anthropic:

model:
  name: anthropic/claude-sonnet-4-5
  # or: anthropic/claude-sonnet-4-20250514

Google:

model:
  name: google/gemini-2.5-flash
  # or: google/gemini-2.0-flash

Model Parameters

Customize model behavior:

model:
  name: openai/gpt-5-mini
  parameters:
    temperature: 0.7        # Creativity (0-2)
    max_tokens: 4000        # Max response length
    top_p: 1.0             # Nucleus sampling (0-1)
    frequency_penalty: 0    # Reduce repetition (-2 to 2)
    presence_penalty: 0     # Encourage new topics (-2 to 2)

Built-in Tools

Control which capabilities your agent has access to:

Execution Tool

Execute shell commands in the agent’s container:

tools:
  exec:
    enabled: true

Use case: Running CLI tools, scripts, system commands

File Reading

Read files from the agent’s workspace:

tools:
  read_file:
    enabled: true

Use case: Viewing file contents, inspecting configurations

File Searching

Search file contents using regex patterns:

tools:
  grep_files:
    enabled: true

Use case: Finding specific code, searching logs

File Editing

Modify files in the agent’s workspace:

tools:
  edit_file:
    enabled: true

Use case: Making code changes, updating configurations

Memory

Persistent memory across conversations:

tools:
  memory:
    enabled: true

Use case: Remembering user preferences, maintaining context

Note: Memory is disabled by default to reduce token usage.

Remote MCP Servers

Connect to Model Context Protocol servers for additional capabilities. Server types can be http or sse:

Basic MCP Configuration

mcpServers:
  context7:
    type: http
    url: "https://mcp.context7.com/mcp"
    headers:
      Authorization: "Bearer ${CONTEXT_7_API_KEY}"

  github:
    type: http
    url: "https://api.githubcopilot.com/mcp"
    headers:
      Authorization: "Bearer ${GITHUB_PAT}"

Environment Variables in Config

Use ${VAR} syntax to reference environment variables:

mcpServers:
  custom_mcp:
    type: http
    url: "${MCP_SERVER_URL}"
    headers:
      Authorization: "Bearer ${MCP_API_KEY}"
      Custom-Header: "${CUSTOM_VALUE:-default}"

Syntax:

• ${VAR} - Expands to value (errors if not set)
• ${VAR:-default} - Uses default if VAR not set

Multi-Agent Configuration (A2A)

Connect your agent to other A2A-compatible agents:

agent:
  name: Coordinator Agent
  description: Orchestrates specialized agents
  model:
    name: openai/gpt-5-mini

  tools:
    memory:
      enabled: true

  # Connect to other agents
  a2a:
    - name: research_agent
      agent_url: "http://agent-research:80"
    - name: writer_agent
      agent_url: "http://agent-writer:80"

Multi-Agent Example

docker-compose.yml:

services:
  research-agent:
    image: brycewcole/capsule-agents:latest
    ports:
      - "8001:9000"
    volumes:
      - ./research.config.yaml:/app/agent.config.yaml
    environment:
      - AGENT_URL=http://localhost:8001
    env_file:
      - .env

  writer-agent:
    image: brycewcole/capsule-agents:latest
    ports:
      - "8002:9000"
    volumes:
      - ./writer.config.yaml:/app/agent.config.yaml
      - ./shared-workspace:/app/agent-workspace
    environment:
      - AGENT_URL=http://localhost:8002
    env_file:
      - .env

  coordinator-agent:
    image: brycewcole/capsule-agents:latest
    ports:
      - "8003:9000"
    volumes:
      - ./coordinator.config.yaml:/app/agent.config.yaml
    environment:
      - AGENT_URL=http://localhost:8003
    env_file:
      - .env
    depends_on:
      - research-agent
      - writer-agent

Scheduled Tasks

Run tasks on a schedule using cron expressions:

schedules:
  - name: daily_report
    prompt: "Generate a daily summary report and save it to reports/"
    cron_expression: "0 9 * * *"  # 9 AM daily
    enabled: true

  - name: hourly_check
    prompt: "Check for new data and process it"
    cron_expression: "0 * * * *"  # Every hour
    enabled: true
    backoff:
      enabled: true
      schedule: [300, 600, 1800]  # Retry after 5min, 10min, 30min on failure

Optional Schedule Fields

  - name: daily_report
    context_id: "existing-context-id" # Reuse a context instead of creating a new one
    hooks:
      - type: discord
        webhookUrl: "https://discord.com/api/webhooks/your-webhook-url"

Note: Changing cron_expression or backoff settings requires a server restart to re-register the Deno cron job.

Cron Expression Format

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Examples:

• 0 9 * * * - Daily at 9 AM
• 0 */6 * * * - Every 6 hours
• 0 0 * * 0 - Weekly on Sunday at midnight
• 30 14 1 * * - Monthly on the 1st at 2:30 PM

Hooks

Integrate with external services for notifications. The only built-in hook today is Discord:

Discord Webhook

agent:
  hooks:
    - type: discord
      enabled: true
      webhookUrl: "https://discord.com/api/webhooks/your-webhook-url"

What gets sent:

• Task completion payloads (including artifacts and schedule metadata if applicable)

Environment Variables

Required Variables

At least one AI provider API key and credentials for the editor/API:

OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...
ADMIN_PASSWORD=secure-password-here
AGENT_URL=http://localhost:8080

The editor/API use HTTP Basic Auth with username admin and the ADMIN_PASSWORD you set.

Optional Variables

# Optional server port (default: 9000)
PORT=9000

# Optional config path override
AGENT_CONFIG_FILE=/app/agent.config.yaml

# Optional workspace directory
WORKSPACE_DIR=/app/agent-workspace

# Optional database path override
DB_PATH=/app/data/sessions.db

# MCP Server credentials
CONTEXT_7_API_KEY=ctx7sk-...
GITHUB_PAT=ghp_...

# Google Vertex AI configuration
GOOGLE_GENAI_USE_VERTEXAI=FALSE

# OpenTelemetry (observability)
OTEL_DENO=true
OTEL_SERVICE_NAME=capsule-api
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Docker Configuration

Basic Run

docker run \
  --env-file .env \
  -e AGENT_URL=http://localhost:8080 \
  -p 8080:9000 \
  -v $(pwd)/agent.config.yaml:/app/agent.config.yaml \
  -it brycewcole/capsule-agents:latest

Volume Mounts

Configuration:

-v $(pwd)/agent.config.yaml:/app/agent.config.yaml

Database persistence:

-v $(pwd)/data:/app/data

Shared workspace:

-v $(pwd)/workspace:/app/agent-workspace

Custom frontend:

-v $(pwd)/custom-frontend:/app/static

Complete Example Configurations

GitHub Manager

agent:
  name: Github Manager
  description: Manages GitHub repositories, issues, and PRs
  model:
    name: openai/gpt-5-mini

  tools:
    exec:
      enabled: true
    read_file:
      enabled: true
    edit_file:
      enabled: true

mcpServers:
  context7:
    type: http
    url: "https://mcp.context7.com/mcp"
    headers:
      Authorization: "Bearer ${CONTEXT_7_API_KEY}"

  github:
    type: http
    url: "https://api.githubcopilot.com/mcp"
    headers:
      Authorization: "Bearer ${GITHUB_PAT}"

Coordinator Agent with Scheduling

agent:
  name: Coordinator Agent
  description: Orchestrates research and writing tasks
  model:
    name: anthropic/claude-sonnet-4-5

  tools:
    memory:
      enabled: true
    exec:
      enabled: true

  a2a:
    - name: research_agent
      agent_url: "http://agent-research:80"
    - name: writer_agent
      agent_url: "http://agent-writer:80"
  hooks:
    - type: discord
      enabled: true
      webhookUrl: "${DISCORD_WEBHOOK_URL}"

schedules:
  - name: daily_summary
    prompt: "Use research_agent to gather latest updates, then writer_agent to create a summary"
    cron_expression: "0 9 * * *"
    enabled: true
    backoff:
      enabled: true
      schedule: [600, 1800, 3600]

Validation and Defaults

The config file is validated on startup against the schema. A few behaviors to be aware of:

• If the configured model is missing or unavailable, the server auto-selects the best available model from the built-in registry.
• If no provider API keys are set, the server logs a warning and no model will be available until a provider key is configured.
• Environment variable expansion in the config file will error if ${VAR} is used and the variable is not set.

Check container logs for validation and startup warnings:

docker logs <container-id>

Best Practices

1. Start simple - Begin with basic config, add features as needed
2. Use environment variables - Never hardcode secrets in YAML
3. Enable memory selectively - Only when context persistence is needed
4. Test cron schedules - Use crontab.guru to validate expressions
5. Monitor token usage - Disable unused tools to reduce costs
6. Backup data volume - Persist /app/data for chat history and memory

Next Steps

• Explore example configurations
• Learn about the A2A protocol
• Review examples