Configuration

CLI launch settings, persistent JSON, generated NixOS configuration, and secret discovery are different inputs. A provider key is not another level in ordinary settings precedence.

Local settings

The launcher merges JSON objects in this order, with later files winning:

/etc/cowboy/config.json
~/.config/cowboy/config.json (under the configured XDG config directory)
.cowboy/config.json in the current directory

Missing, unreadable, malformed, and non-object files contribute no settings. Explicit CLI options override the corresponding ordinary settings.

For provider, main model, and heartbeat, merged files override generated agent JSON, which overrides built-in defaults. For secondary models and memory/rerank settings, generated agent JSON overrides merged files; supported CLI options still win. Do not assume one precedence order covers every field. The declared systemd daemon takes its arguments from NixOS configuration directly, rather than reading the operator’s local launch defaults.

A local config can contain:

{
  "provider": "anthropic",
  "model": "claude-opus-4-5-20251101",
  "log_level": "info"
}

Common settings subset

This is a common subset, not the entire recognized surface. The implementation inventory is crates/contracts/src/keys.rs; a host or launcher need not expose every component key as a CLI option.

Key	Meaning
`provider`	Provider for the main model
`model`	Bare model ID in local JSON; provider comes from the separate key
`summary_model`	Provider:model specification for summarization
`compact_model`	Provider:model specification for compaction
`subagent_model`	Provider:model specification for sub-agents
`vision_model`	Native vision or a separate provider:model specification
`memory_backend`	Memory search backend
`heartbeat`	Launcher heartbeat interval, in seconds
`log_level`	Logging verbosity

The component key for heartbeat is heartbeat_interval; the launcher’s JSON setting and flag use heartbeat and --heartbeat. Model availability and provider access are separate: selecting a model does not provision credentials. Use cowboy models to inspect the bundled catalog and each command’s --help for its options.

Secrets

Outside proxy deployments, discovery checks each key in this order and uses the first nonempty value:

Provider environment variable, such as ANTHROPIC_API_KEY.
User keys file, ~/.config/cowboy/keys.json.
System keys file, /etc/cowboy/keys.json.
The provider’s agenix file, if readable.

Keys files map component key names, such as anthropic_api_key, to secret values. They must have mode 0600: files accessible to group or other users are skipped with a warning. Secret files and environment variables remain real credentials in local and ordinary Docker deployments.

Managed daemons receive proxy placeholders. The actual key belongs at the secret path named by the proxy domain mapping, readable by the proxy service user. The managed installation shows an agenix declaration with that ownership.

First-boot settings

A --settings file for cowboy init or cowboy serve is a validated bootstrap input, not the general config file. It accepts a key reference through api_key_env or api_key_file; a literal api_key is rejected. For example:

{
  "agent_name": "myagent",
  "posture": "container",
  "provider": "anthropic",
  "model": "claude-opus-4-5-20251101",
  "api_key_env": "ANTHROPIC_API_KEY"
}

The host resolves the reference and writes the key into the agent’s configuration volume with mode 0600. A bootstrapped volume rejects restaging; edit its persistent configuration instead. See daily operation for generation and backup considerations.

NixOS module

Import the default NixOS module and enable individual agents under services.cowboy.agents. There is no top-level service enable switch. Keep agent usernames equal to their agent names when using Redis ACLs, and give each enabled agent a unique UID.

The main model option takes a provider:model specification. Common per-agent options include homeDirectory, prompts.system, mounts, daemon.enable, and daemon.expose. The latter provides an authenticated control endpoint; daemon.observe provides a separate read-only endpoint and credential.

Nix generates per-agent launch configuration and components, and message-source configuration for agents and bridges. Edit the Nix declaration, not the generated files under /etc/cowboy. The full per-agent schema is in modules/options/user.nix.

Managed provider access is provisioned from the model options. To keep another keyed provider available for a runtime model switch, declare it in extraProviders and provision its proxy secret. This grants provider access; it does not select the main model.

Continue with tools and skills and bridge integration.