Configuration

Cowboy provides flexible configuration through multiple methods to suit different deployment scenarios, from local development to production NixOS systems.

Configuration Methods Overview

MethodUse CasePrioritySecurity Level
CLI ArgumentsQuick testing, one-off commandsHighestModerate
Environment VariablesSecrets, dynamic valuesMediumHigh
Config FileLocal development, persistent settingsMediumLow
NixOS/Home ManagerProduction, declarative systemsLowestHighest

1. Configuration File

Location

  • System-wide: /etc/cowboy/config.toml
  • User-specific: ~/.config/cowboy/config.toml
  • Development: ./cowboy.toml

Example Configuration

# ~/.config/cowboy/config.toml

# Primary model configuration
provider = "anthropic"
model = "claude-opus-4-6"

# Secondary models for specialized tasks
summary_model = "openai:gpt-4.1"
compact_model = "openai:gpt-4.1"
subagent_model = "openrouter:xiaomi/mimo-v2-flash"

# Enable features
memory_enabled = true
chrome = false  # Show Zellij UI chrome

# Tool configuration
[tools]
bash_enabled = true
bash_timeout = 120
web_search_enabled = false
read_enabled = true
write_enabled = true

# Security settings
[security]
require_approval = ["write", "bash::rm", "bash::mv"]
max_tool_calls_per_session = 100
execution_timeout = 3600

# API keys (use environment variables in production)
[api_keys]
anthropic = "${ANTHROPIC_API_KEY}"
openai = "${OPENAI_API_KEY}"
exa = "${EXA_API_KEY}"
openrouter = "${OPENROUTER_API_KEY}"

# Memory configuration
[memory]
backend = "zk"  # or "qmd" for hybrid search
database_path = "~/.local/share/cowboy/memory.db"
max_entries = 10000
prune_after_days = 30

# Workspace configuration
[workspace]
directory = "~/workspace"
context_file = "context.md"

2. Environment Variables

Environment variables provide a secure way to configure Cowboy, especially for secrets.

Basic Configuration

# Model selection
export COWBOY_PROVIDER="anthropic"
export COWBOY_MODEL="claude-opus-4-6"

# Secondary models
export COWBOY_SUMMARY_MODEL="openai:gpt-4.1"
export COWBOY_COMPACT_MODEL="openai:gpt-4.1"
export COWBOY_SUBAGENT_MODEL="openrouter:xiaomi/mimo-v2-flash"

# Feature flags
export COWBOY_MEMORY_ENABLED="true"
export COWBOY_CHROME="false"

API Keys

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Exa (Web search)
export EXA_API_KEY="exa-..."

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."

Security Settings

# Tools requiring approval
export COWBOY_REQUIRE_APPROVAL="write,bash::rm,bash::mv"

# Execution limits
export COWBOY_MAX_TOOL_CALLS="100"
export COWBOY_EXECUTION_TIMEOUT="3600"

Memory Configuration

# Memory backend
export COWBOY_MEMORY_BACKEND="zk"  # or "qmd"

# Database path
export COWBOY_MEMORY_DB_PATH="/home/user/.local/share/cowboy/memory.db"

# Memory limits
export COWBOY_MEMORY_MAX_ENTRIES="10000"
export COWBOY_MEMORY_PRUNE_DAYS="30"

3. Command Line Arguments

CLI arguments provide the highest priority configuration, perfect for testing and one-off commands.

Basic Usage

# Specify model directly
cowboy --model anthropic:claude-opus-4-6

# With a task
cowboy --model openai:gpt-4.1 --task "Review the codebase for security issues"

# Web server mode
cowboy --web --port 8080 --model anthropic:claude-opus-4-6

# Stop running session
cowboy --stop --session my-session

Advanced Options

# Multiple model specifications
cowboy \
  --model anthropic:claude-opus-4-6 \
  --summary-model openai:gpt-4.1 \
  --compact-model openai:gpt-4.1

# Debug and logging
cowboy --debug debug --model anthropic:claude-opus-4-6

# Custom WASM binary
cowboy --wasm /path/to/custom-harness.wasm --model anthropic:claude-opus-4-6

# Chrome UI (show Zellij panes)
cowboy --chrome --model anthropic:claude-opus-4-6

4. NixOS Module Configuration

For system-wide deployment on NixOS, use the declarative NixOS module.

Basic System Configuration

# configuration.nix
{ config, pkgs, inputs, ... }:

{
  imports = [ inputs.cowboy.nixosModules.default ];

  services.cowboy = {
    enable = true;
    
    agents = {
      agent = {
        enable = true;
        user = "cowboy";
        uid = 1338;
        homeDirectory = "/home/cowboy";
        
        # Model configuration
        model = "anthropic:claude-opus-4-6";
        summaryModel = "openai:gpt-4.1";
        compactModel = "openai:gpt-4.1";
        
        # Memory backend
        memoryBackend = "zk";
        
        # Prompts
        prompts = {
          system = ''
            You are Cowboy, an AI coding assistant. You follow these rules:
            1. Always use tools to accomplish tasks
            2. Never give step-by-step instructions for manual execution
            3. Iterate on failure with different approaches
          '';
        };
      };
    };
  };
}

With Secrets Management (agenix)

# configuration.nix
{ config, pkgs, inputs, ... }:

{
  imports = [
    inputs.cowboy.nixosModules.default
    inputs.agenix.nixosModules.default
  ];

  # agenix secrets
  age.secrets = {
    anthropic-key = {
      file = ./secrets/anthropic.age;
      owner = "cowboy";
      group = "cowboy";
    };
    openai-key = {
      file = ./secrets/openai.age;
      owner = "cowboy";
      group = "cowboy";
    };
  };

  services.cowboy = {
    enable = true;
    
    agents.agent = {
      enable = true;
      model = "anthropic:claude-opus-4-6";
      
      environment = {
        ANTHROPIC_API_KEY = config.age.secrets.anthropic-key.path;
        OPENAI_API_KEY = config.age.secrets.openai-key.path;
      };
    };
  };
}

With Security Sandbox (Network Namespace)

# configuration.nix
{ config, pkgs, inputs, ... }:

{
  imports = [ inputs.cowboy.nixosModules.default ];

  services.cowboy = {
    enable = true;
    
    # Enable security proxy
    secretsProxy.enable = true;
    
    agents.agent = {
      enable = true;
      model = "anthropic:claude-opus-4-6";
      
      # Network namespace for isolation
      namespace = "cowboy-agent";
      
      environment = {
        ANTHROPIC_API_KEY = "/run/agenix/anthropic-key";
      };
    };
    
    # API key mappings for proxy
    secretsProxy.domainMappings = {
      "api.anthropic.com" = {
        secretPath = "/run/agenix/anthropic-key";
        headerName = "x-api-key";
      };
    };
  };
}

5. Home Manager Configuration

For user-level installation without root access.

Basic Home Manager

# home.nix
{ config, pkgs, inputs, ... }:

{
  imports = [ inputs.cowboy.homeManagerModules.default ];

  programs.cowboy = {
    enable = true;
    
    settings = {
      provider = "anthropic";
      model = "claude-opus-4-6";
      memory_enabled = true;
      
      tools = {
        bash_enabled = true;
        web_search_enabled = true;
      };
    };
    
    environment = {
      ANTHROPIC_API_KEY = "$ANTHROPIC_API_KEY";
      EXA_API_KEY = "$EXA_API_KEY";
    };
  };
}

Advanced Home Manager with Multiple Agents

# home.nix
{ config, pkgs, inputs, ... }:

{
  imports = [ inputs.cowboy.homeManagerModules.default ];

  programs.cowboy = {
    enable = true;
    
    agents = {
      coding = {
        model = "anthropic:claude-opus-4-6";
        memory_backend = "qmd";  # Hybrid search
      };
      
      research = {
        model = "openrouter:xiaomi/mimo-v2-flash";
        memory_backend = "zk";  # Keyword search
      };
    };
  };
}

6. Tool Configuration

Enabling/Disabling Tools

# config.toml
[tools]
bash_enabled = true
bash_timeout = 120

web_search_enabled = true
web_search_num_results = 10

read_enabled = true
write_enabled = true
search_enabled = true
find_enabled = true

Tool-Specific Settings

[tools.bash]
enabled = true
timeout = 120
allowed_commands = ["ls", "pwd", "cat", "grep", "find"]
blocked_patterns = ["rm -rf", "dd if=/dev/random", ":(){:|:&};:"]

[tools.write]
enabled = true
allowed_paths = [
  "/home/user/projects/",
  "/tmp/",
  "*.md",
  "*.rs",
  "*.toml"
]

[tools.web_search]
enabled = true
num_results = 10
provider = "exa"

Custom Tool Filters

[security.filters]
# Block specific command patterns
bash_block_patterns = [
  "rm -rf /",
  "dd if=/dev/random",
  ":(){:|:&};:"  # Fork bomb
]

# Allow only specific directories
write_allowed_paths = [
  "/home/user/projects/",
  "/tmp/",
  "*.md",  # Only markdown files
]

# File extension restrictions
read_allowed_extensions = [".md", ".txt", ".rs", ".toml", ".nix"]

7. Memory Configuration

Backend Selection

# config.toml
[memory]
# Options: "zk" (Zettelkasten), "qmd" (Hybrid)
backend = "zk"

# Zettelkasten configuration
[memory.zk]
database_path = "~/.local/share/cowboy/memory.db"
max_entries = 10000
prune_after_days = 30

# Search settings
search_enabled = true
search_threshold = 0.7

QMD (Hybrid) Backend

[memory]
backend = "qmd"

[memory.qmd]
database_path = "~/.local/share/cowboy/memory.db"
vector_model = "all-MiniLM-L6-v2"
bm25_weight = 0.4
vector_weight = 0.6
reranking_enabled = true

Environment Variables for Memory

# Memory backend
export COWBOY_MEMORY_BACKEND="zk"

# Database configuration
export COWBOY_MEMORY_DB_PATH="/home/user/.local/share/cowboy/memory.db"
export COWBOY_MEMORY_MAX_ENTRIES="10000"
export COWBOY_MEMORY_PRUNE_DAYS="30"

# Search settings
export COWBOY_MEMORY_SEARCH_THRESHOLD="0.7"

8. Security Configuration

Approval Workflow

# config.toml
[security]
# Tools requiring manual approval
require_approval = [
  "write",
  "bash::rm",
  "bash::mv",
  "bash::sudo",
  "web_search"
]

# Execution limits
max_tool_calls_per_session = 100
execution_timeout = 3600  # 1 hour

Network Isolation (NixOS)

# configuration.nix
services.cowboy = {
  enable = true;
  
  # Enable network namespace isolation
  secretsProxy.enable = true;
  
  agents.agent = {
    enable = true;
    namespace = "cowboy-agent";
    
    # API key mappings for proxy injection
    environment = {
      ANTHROPIC_API_KEY = "/run/agenix/anthropic-key";
    };
  };
  
  # Proxy configuration
  secretsProxy.domainMappings = {
    "api.anthropic.com" = {
      secretPath = "/run/agenix/anthropic-key";
      headerName = "x-api-key";
    };
  };
};

Sandbox Configuration

# config.toml
[security.sandbox]
enabled = true
network_isolation = true
file_system_restrictions = true
max_memory_mb = 1024
max_cpu_percent = 50

9. Production Deployment Recommendations

1. Use NixOS Modules

Always use the NixOS module for production deployments:

services.cowboy.enable = true;

2. Secure Secrets Management

  • Use agenix, sops, or similar for secrets
  • Never store secrets in configuration files
  • Use environment variable references or secret paths
age.secrets.anthropic-key.file = ./secrets/anthropic.age;

3. Enable Security Features

services.cowboy = {
  secretsProxy.enable = true;
  agents.agent.namespace = "cowboy-agent";
};

4. Configure Resource Limits

[security]
max_tool_calls_per_session = 100
execution_timeout = 3600

5. Set Up Monitoring

# Monitor agent heartbeat
systemd.user.services.cowboy-heartbeat = {
  enable = true;
  serviceConfig = {
    Type = "oneshot";
    ExecStart = "${pkgs.coreutils}/bin/touch /run/user/%U/cowboy-heartbeat";
  };
};

6. Use Declarative Configuration

# Everything in Nix configuration
services.cowboy.agents.agent = {
  enable = true;
  model = "anthropic:claude-opus-4-6";
  memoryBackend = "zk";
  # ... all other settings
};

10. Configuration Validation

Validate Configuration File

# Test configuration file syntax
cowboy --config test.toml --validate

# Dry run to see effective configuration
cowboy --config production.toml --dry-run

# Show current configuration
cowboy --show-config

Check NixOS Configuration

# Build and test NixOS configuration
nixos-rebuild dry-activate

# Check configuration syntax
nix-instantiate --eval -E 'import ./configuration.nix'

Environment Variable Testing

# Test with specific environment
export COWBOY_MODEL="anthropic:claude-opus-4-6"
cowboy --model openai:gpt-4.1  # CLI overrides env var

11. Priority and Resolution

Configuration is resolved in this order (highest to lowest priority):

  1. CLI Arguments (--model, --debug, etc.)
  2. Environment Variables (COWBOY_*)
  3. Configuration File (config.toml)
  4. NixOS/Home Manager (declarative)
  5. Hardcoded Defaults (anthropic:claude-opus-4-6)

Example Resolution

# CLI argument wins
cowboy --model openai:gpt-4.1

# Environment variable overrides config file
export COWBOY_MODEL="anthropic:claude-opus-4-6"
# config.toml has: model = "openai:gpt-4.1"
# Result: Uses anthropic:claude-opus-4-6 from env var

12. Common Configuration Scenarios

Development Environment

# ~/.config/cowboy/config.toml
provider = "anthropic"
model = "claude-opus-4-6"
memory_enabled = true

[tools]
bash_enabled = true
web_search_enabled = true

[security]
require_approval = ["write", "bash::rm"]
max_tool_calls_per_session = 50

Production Server

# NixOS configuration
services.cowboy.agents.agent = {
  enable = true;
  model = "anthropic:claude-opus-4-6";
  memoryBackend = "zk";
  
  prompts.system = ''
    You are Cowboy, operating in production mode.
    Always use approval workflows for sensitive operations.
  '';
};

Research Agent

# config.toml
provider = "openrouter"
model = "xiaomi/mimo-v2-flash"
memory_backend = "qmd"  # Hybrid search for research

[tools]
web_search_enabled = true
web_search_num_results = 20

Development Agent

# config.toml
provider = "openai"
model = "gpt-4.1"

[tools]
bash_enabled = true
bash_timeout = 300

[security]
require_approval = ["bash::sudo", "write::/etc"]

Next Steps