Configuration

Cowboy is configured at three layers, in increasing order of precedence:

1. CLI flags passed to cowboy or harness.
2. Config files (JSON).
3. Environment variables and keyring entries for API keys.

In NixOS deployments the NixOS module does not write /etc/cowboy/config.json (that file is an optional, hand-written system default). Instead it generates per-agent runtime config: /etc/cowboy/agents/<name>.json, /etc/cowboy/plugins.json, and /etc/cowboy/cowboy/sources.json; see NixOS module below.

Config files

Config files are plain JSON. They are merged in this order, with later files overriding earlier ones:

1. /etc/cowboy/config.json — optional hand-written system defaults (not emitted by the NixOS module).
2. ~/.config/cowboy/config.json — user overrides.
3. .cowboy/config.json — project overrides (lite mode).

A config file is a flat JSON object whose keys are forwarded to the WASM plugin. Only the keys listed in Config keys are recognized.

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "summary_model": "openai:gpt-4.1",
  "compact_model": "openai:gpt-4.1",
  "memory_backend": "qmd",
  "debug": "info"
}

There is no command to generate or validate this file; it is read directly if present and ignored if missing or malformed.

Config keys

These keys are read from the merged config file by the launcher (and the matching KDL keys are forwarded to the WASM plugin). Unless noted, a key is optional.

The launcher also forwards runtime values the plugin needs that are not normally set by hand: data_dir, config_dir, workspace_dir, home_dir, agent_name, wasm_path, initial_prompt, exit_on_idle, and ollama_base_url (from the OLLAMA_BASE_URL environment variable when provider is ollama). For Codex, the full NixOS deployment supplies subscription credentials through the credential proxy; no Codex API key is placed in the agent configuration.

Environment variables

API keys are discovered from the environment (and, on NixOS, from agenix files). The recognized variables are:

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export OPENROUTER_API_KEY="..."
export EXA_API_KEY="..."        # web search tool
export OLLAMA_BASE_URL="..."    # optional, for a remote ollama server

If no key is found and the provider is not ollama, the launcher prints a warning and continues.

CLI flags

Both entry points (cowboy, the portable launcher, and harness, the full NixOS launcher) share a common set of flags. CLI flags override config-file values.

cowboy adds:

harness adds:

Examples

# Interactive session with an explicit model
cowboy --model anthropic:claude-sonnet-4-20250514

# Distinct models for the main agent and the background tasks
cowboy \
  --model anthropic:claude-opus-4-5-20251101 \
  --summary-model openai:gpt-4.1 \
  --compact-model openai:gpt-4.1

# One-shot, non-interactive run
cowboy -q "Summarize the changes on this branch"

# Stop a named session
cowboy --stop --session my-session

Subcommands

cowboy exposes a number of verbs beyond the bare session launch (run cowboy --help for the full list); this page covers only the config-relevant one. For example, cowboy plugins lists Cowboy plugins registered in /etc/cowboy/plugins.json (NixOS deployments); it takes no flags.

Models

A model is selected as provider:model (via --model or the config provider and model keys). The models defined in the harness are:

A few short aliases are mapped to their canonical Anthropic IDs:

• claude-4-6, claude-4.6 → claude-sonnet-4-20250514
• claude-4-5, claude-4.5 → claude-opus-4-5-20251101

OpenRouter names containing a / are passed through unchanged.

NixOS module

The NixOS module is exposed as inputs.cowboy.nixosModules.default (and inputs.cowboy.darwinModules.default for nix-darwin). There is no separate home-manager module; the NixOS module manages the agent’s home-manager configuration internally.

Agents are defined under services.cowboy.agents.<name> and enabled individually with enable = true. There is no top-level services.cowboy.enable. The single-agent alias services.cowboy.agent is shorthand for services.cowboy.agents.agent.

Per-agent options

The most commonly set per-agent options:

Additional option groups exist for finer control: judge.* (idle-judge model, criteria, escalation levels), workspace.* and mounts (bind mounts into the agent’s workspace), sheepdog.* (per-agent allow/deny rules and blocked syscalls), daemon.* (persistent session resource limits), schedules (systemd-calendar prompts), and skills.homeAssistant.*. Consult modules/options/user.nix for the full schema and defaults.

The top-level services.cowboy.mode (single or multi) controls agent topology; it defaults to single when at most one agent is enabled.

Example

{ config, inputs, ... }:

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

  services.cowboy.agents.agent = {
    enable = true;
    user = "cowboy";
    uid = 1338;

    model = "anthropic:claude-sonnet-4-20250514";
    summaryModel = "openai:gpt-4.1";
    compactModel = "openai:gpt-4.1";
    memoryBackend = "qmd";

    prompts.system = ''
      You are a coding agent. Prefer using tools over describing manual steps.
    '';
  };
}

Enforcement (on by default)

Cowboy’s three enforcement substrates are on by default — the credential proxy everywhere, the Redis ACL and the syscall sandbox on Linux (neither exists on darwin):

services.cowboy.secretsProxy.enable    # default: true
services.cowboy.pubsub.redisAcl.enable # default: true on Linux, false on darwin
services.cowboy.sheepdog.enable        # default: true on Linux, false on darwin

The credential proxy needs provider secrets at the agenix paths it expects, so a fresh host that does not have them yet has to turn it off deliberately. Whatever you turn off is named in an eval-time warning that says what stopped holding — the warnings follow what is enabled, so nothing goes quiet. See the security model.

Other sub-trees

The module exposes several optional subsystems, each with its own enable. The first two are on by default:

• services.cowboy.secretsProxy.enable — credential-injecting proxy for agent network isolation.
• services.cowboy.sheepdog.enable — syscall-level enforcement of tool-execution permissions (Linux only).
• services.cowboy.camoufox.enable — browser service for agents.
• services.cowboy.pubsub and services.cowboy.bridges — message bus and bridge services (Discord, email).

Related guides

• Memory system — the zk and qmd backends.
• Sub-agents — sub-agent models and prompts.
• Security model — sheepdog, the secrets proxy, and network isolation.

Project site: https://cowboy.rs. Source: https://github.com/dmadisetti/cowboy.