Getting Started

This guide walks you through installing herdctl and running your first autonomous agent fleet. By the end, you’ll have a working fleet with visible output confirming success.

Prerequisites

Before you begin, ensure you have:

• Node.js 20+ - herdctl requires Node.js 20 or later
• Claude Code CLI - Agents use Claude Code under the hood (install instructions)
• Git - For workspace management and repo cloning

Installation

pnpm

# Install as a global CLI tool
pnpm add -g herdctl

# Or install the library in your project
pnpm add @herdctl/core

npm

# Install as a global CLI tool
npm install -g herdctl

# Or install the library in your project
npm install @herdctl/core

Verify the installation:

herdctl --version

Quick Start: Your First Fleet

1. Create a project directory

   mkdir my-fleet && cd my-fleet

2. Create the fleet configuration (herdctl.yaml)

   herdctl.yaml

   version: 1
   
   agents:
     - path: ./agents/hello-agent.yaml

3. Create an agent configuration (agents/hello-agent.yaml)

   mkdir -p agents

   agents/hello-agent.yaml

   name: hello-agent
   description: "A simple agent that says hello"
   
   schedules:
     greet:
       type: interval
       interval: 30s
       prompt: "Say hello and report the current time."

4. Start the fleet

   herdctl start

5. Verify it’s working

   You should see output like:

   ✓ Fleet initialized with 1 agent
   ✓ Scheduler started
   ✓ hello-agent/greet triggered

Using herdctl as a Library

For programmatic control, use the @herdctl/core package directly. Here’s a minimal example extracted from the test suite:

quickstart.ts

import { FleetManager } from "@herdctl/core";

const manager = new FleetManager({
  configPath: "./herdctl.yaml",
  stateDir: "./.herdctl",
});

await manager.initialize();
await manager.start();

manager.on("job:created", (payload) => {
  console.log(`Job created: ${payload.job.id}`);
});

manager.on("schedule:triggered", (payload) => {
  console.log(`${payload.agentName}/${payload.scheduleName} triggered`);
});

// Keep running until interrupted
process.on("SIGINT", async () => {
  await manager.stop();
  process.exit(0);
});

This example:

• Creates a FleetManager with your config
• Initializes and starts the fleet
• Listens for job and schedule events
• Handles graceful shutdown

Tip

The FleetManager auto-creates the .herdctl/ state directory if it doesn’t exist.

Required Files and Directories

Configuration Files

File	Purpose	Required
herdctl.yaml	Fleet configuration (agents list, defaults)	Yes
agents/*.yaml	Individual agent configurations	At least one

State Directory (.herdctl/)

herdctl automatically creates and manages a .herdctl/ directory to track fleet state:

.herdctl/
├── state.yaml        # Fleet state (agent status, schedules)
├── jobs/             # Job metadata and output
│   ├── job-*.yaml    # Job metadata (YAML)
│   └── job-*.jsonl   # Job streaming output (JSONL)
└── sessions/         # Claude session data for resume capability

Note

The .herdctl/ directory is created automatically. You don’t need to create it manually. Add it to your .gitignore if you don’t want to track state in version control.

Configuration Reference

Minimal Fleet Config

The simplest fleet configuration:

herdctl.yaml

version: 1

agents:
  - path: ./agents/my-agent.yaml

Minimal Agent Config

The simplest agent configuration:

agents/my-agent.yaml

name: my-agent

An agent without schedules can still be triggered manually via the CLI or API.

Typical Agent Config

A more realistic agent that processes work periodically:

agents/coder.yaml

name: coder
description: "Implements features from GitHub issues"

schedules:
  check-issues:
    type: interval
    interval: 5m
    prompt: |
      Check for GitHub issues labeled "ready".
      Implement the oldest one and create a PR.

permission_mode: acceptEdits
allowed_tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

CLI Commands

Once your fleet is configured, use these commands:

# Start the fleet (all agents)
herdctl start

# Start a specific agent
herdctl start coder

# Check fleet status
herdctl status

# Manually trigger an agent
herdctl trigger coder check-issues

# View logs
herdctl logs coder

# Stop the fleet
herdctl stop

Verifying Your Setup

After starting your fleet, you can verify it’s working:

Check Fleet Status

herdctl status

Expected output:

Fleet: running
Agents: 1 total, 1 idle
Schedules: 1 active

Agents:
  hello-agent    idle    greet: next run in 25s

Check Logs

herdctl logs hello-agent

Inspect State Files

# View fleet state
cat .herdctl/state.yaml

# List jobs
ls .herdctl/jobs/

# View a job's output
cat .herdctl/jobs/job-*.jsonl

Troubleshooting

Fleet won’t start

1. Check config syntax: herdctl config validate
2. Verify agent paths: Ensure paths in agents: are correct relative to herdctl.yaml
3. Check permissions: Ensure you have write access to the directory for .herdctl/

Agent not triggering

1. Check schedule syntax: Intervals must be valid (e.g., 5m, 1h, 30s)
2. View schedule state: herdctl status shows next trigger times
3. Check logs: herdctl logs <agent-name> for errors

Jobs failing

1. Check Claude Code CLI: Ensure claude is installed and authenticated
2. Check permissions: Verify the agent has necessary tool permissions
3. View job output: cat .herdctl/jobs/job-*.jsonl for detailed output

Next Steps

Fleet Configuration Learn all fleet config options including defaults and workspace settings

Agent Configuration Deep dive into agent config: schedules, permissions, work sources

Schedules Understand interval, cron, webhook, and chat triggers

State Management How herdctl tracks fleet state, jobs, and sessions

Core Concepts

Before diving deeper, understand these key concepts:

Concept	Description
Fleet	Collection of agents defined in herdctl.yaml
Agent	A configured Claude instance with identity, schedules, and permissions
Schedule	Defines when (trigger) and how (prompt) to invoke an agent
Job	A single execution of an agent, with unique ID and tracked output
Workspace	Isolated directory where an agent operates

Agents What agents are and how they operate

Jobs How job executions are tracked

Triggers All trigger types: interval, cron, webhook, chat

Workspaces Agent working directories and isolation