Skip to Content
GuidesWorkflowsFleet Quick Start

Fleet Quick Start

Get up and running with Agent Harbor’s fleet architecture in minutes. This guide walks you through setting up an access point, enrolling followers, and running your first cross-platform command.

Prerequisites

  • Agent Harbor CLI (ah) installed
  • For VM fleets: SSH access to target machines
  • For container fleets: Docker or Podman

Local Development Setup

The fastest way to try the fleet architecture is with local processes.

1. Start the Access Point

# Start access point with fleet services enabled
ah agent access-point \
  --fleet-listen 127.0.0.1:4433 \
  --fleet-name local-dev \
  --fleet-config examples/fleet-local-dev.toml

2. Enroll Followers

In separate terminals, enroll two followers:

# Terminal 2: First follower
ah agent enroll \
  --remote-server https://127.0.0.1:4433 \
  --name worker-1 \
  --os linux \
  --tag role=primary
 
# Terminal 3: Second follower
ah agent enroll \
  --remote-server https://127.0.0.1:4433 \
  --name worker-2 \
  --os linux \
  --tag role=secondary

3. Verify Fleet

Check that followers are enrolled:

ah agent followers list

Output:

Fleet: local-dev
Enrolled followers: 2

NAME       OS     STATUS   TAGS
worker-1   linux  ready    role=primary
worker-2   linux  ready    role=secondary

4. Run Commands

Execute a command on all followers:

ah agent followers run --all -- echo "Hello from fleet"

Output:

{
  "session": { "id": "sess-abc123", "fleet": "local-dev" },
  "results": [
    { "host": "worker-1", "exit_code": 0, "stdout": "Hello from fleet\n" },
    { "host": "worker-2", "exit_code": 0, "stdout": "Hello from fleet\n" }
  ]
}

Container Fleet Setup

For isolated testing, use containers.

1. Create docker-compose.yml

version: '3.8'
services:
  access-point:
    image: agent-harbor:latest
    command: >
      ah agent access-point
      --fleet-listen 0.0.0.0:4433
      --fleet-name container-fleet
    ports:
      - '4433:4433'
 
  worker-1:
    image: agent-harbor:latest
    command: >
      ah agent enroll
      --remote-server https://access-point:4433
      --name worker-1
      --os linux
      --real-exec
    depends_on:
      - access-point
 
  worker-2:
    image: agent-harbor:latest
    command: >
      ah agent enroll
      --remote-server https://access-point:4433
      --name worker-2
      --os linux
      --real-exec
    depends_on:
      - access-point

2. Start the Fleet

docker-compose up -d

3. Run Commands

docker exec access-point ah agent followers run --all -- uname -a

VM Fleet Setup

For cross-platform testing with real VMs.

1. Configure Fleet

Create fleet.toml:

[fleet]
name = "cross-platform"
concurrency = 3
connect-timeout-secs = 30
 
[[vms]]
name = "linux-vm"
hostname = "192.168.1.100"
username = "agent"
port = 22
os = "linux"
workspace = "~/workspace"
 
[[vms]]
name = "macos-vm"
hostname = "192.168.1.101"
username = "agent"
port = 22
os = "macos"
workspace = "~/workspace"

2. Verify Connectivity

ah-fleet-orchestrator verify --config fleet.toml

3. Provision VMs

ah-fleet-orchestrator provision --config fleet.toml

This installs Nix and required tools on each VM.

4. Sync and Build

ah-fleet-orchestrator full --config fleet.toml

Targeting Specific Hosts

By Tag

# Run only on Linux hosts
ah agent followers run --tag os=linux -- cargo test
 
# Run on primary role hosts
ah agent followers run --tag role=primary -- npm test

By Name

ah agent followers run --host worker-1 -- echo "Only on worker-1"

All Hosts

ah agent followers run --all -- make test

Sync Fence

Before running tests, sync local changes to all followers:

# Sync changes
ah agent followers sync-fence
 
# Then run tests
ah agent followers run --all -- pytest

Or combine with the --fence flag:

ah agent followers run --all --fence -- pytest

JSON Output

For programmatic use, add --json:

ah agent followers list --json
ah agent followers run --all --json -- echo test

Next Steps

Example Configurations

Pre-built configurations are available in the examples/ directory:

  • fleet-local-dev.toml - Local development with mock execution
  • fleet-container.toml - Docker/Podman containerized fleet
  • fleet-cross-platform.toml - Linux and macOS VMs
  • fleet-two-linux-vms.toml - Simple two-VM Linux setup
OverviewLong-Horizon Tasks