reference

fleet.yaml

The declarative source of truth for your agents. dclaw up reads this file and reconciles. Validated on load — the daemon refuses to start with an invalid fleet.

Default location: ~/.config/dclaw/fleet.yaml (XDG-aware).

Example

# fleet.yaml — declarative agent fleet
version: 1

defaults:
  image: dclaw-agent:v0.1
  model: anthropic/claude-3-5-sonnet
  max_cost_usd: 10

agents:
  - name: code-reviewer
    workspace: ~/repos/main-app
    model: anthropic/claude-3-5-sonnet
    channels: [slack:#code-reviews]
    max_cost_usd: 25

  - name: oncall-triage
    workspace: ~/dclaw/oncall
    model: openai/gpt-4o
    channels: [discord:#alerts, slack:#ops]
    network_allowlist:
      - api.pagerduty.com
      - api.linear.app

  - name: scratch
    workspace: ~/dclaw/scratch
    # inherits image, model, max_cost from defaults
yaml

Top-level keys

version

Schema version. Currently 1. Required.

defaults

Inherited by every agent unless overridden. Optional.

agents

List of agent specs. At least one required.

Agent spec

name

Unique identifier. [a-z0-9-]+, max 32 chars. Required.

image

OCI image. Defaults to dclaw-agent:v0.1.

workspace

Host path. Validated against denylist + symlink-resolved. Required.

workspace_trust

Bool. Bypass denylist. Logged. Default false.

model

Provider/model string. Routed via pi-mono. anthropic/* · openai/* · google/* · openrouter/*.

channels

List of channel:target. e.g. slack:#ops, discord:#alerts. Plugin must be installed.

network_allowlist

FQDNs the agent can reach. Empty = LLM provider only. CIDRs not yet supported.

max_cost_usd

Hard spend cap. Daemon enforces; container is killed when hit.

env

Map of name → value. Passed at container start. Never written to disk.

Validation is strict

Unknown keys are an error, not a warning. This is intentional — silently ignoring typos is how you end up with a workspace pointing somewhere you didn't expect.

Reconciliation

When you run dclaw up:

Missing agents (in fleet, not running) → created.
Drifted agents (running, but spec changed) → recreated. Workspace preserved.
Matching agents (running, spec matches) → left alone.
Orphaned agents (running, not in fleet) → flagged in dclaw status but not removed. Use dclaw agent destroy explicitly.