Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

examples/ — Fleet Configurations & How-To Guides

This directory contains ready-to-use fleet.yaml configurations and generated output for different deployment scenarios. Each subdirectory demonstrates a complete workflow from fleet topology → generation → runtime monitoring.

Quick Start

Pick an example that matches your setup:

# Single machine — everything on one laptop
subagent-fleet validate --config examples/ollama-laptop-only/fleet.yaml
subagent-fleet generate --config examples/ollama-laptop-only/fleet.yaml

# Multi-machine cluster — laptop + Mac mini + GPU workstation
subagent-fleet validate --config examples/multi-node-cluster/fleet.yaml
subagent-fleet generate --config examples/multi-node-cluster/fleet.yaml

Example Fleet Configurations

ollama-laptop-only/ — Single Machine, Multiple Models

For developers who have Ollama running locally on their laptop with multiple models.

# examples/ollama-laptop-only/fleet.yaml
project:
  name: dev-laptop
  gateway:
    provider: litellm
    host: 0.0.0.0
    port: 4000

nodes:
  laptop:
    endpoint: http://localhost:11434
    tags: [local, fast, controller]

models:
  heavy-coder:
    node: laptop
    ollama_model: qwen2.5-coder:32b
    litellm_alias: claude-sonnet-local
    context: 32768

  small-coder:
    node: laptop
    ollama_model: qwen2.5-coder:7b
    litellm_alias: claude-haiku-local
    context: 8192

agents:
  planner:
    model: small-coder
    description: Use for planning and file discovery.
    tools: [Read, Grep, Glob]

  implementer:
    model: heavy-coder
    description: Use for implementation and refactoring.
    tools: [Read, Grep, Glob, Edit, MultiEdit, Bash]

When to use: You have one machine running Ollama with both a small model (for planning) and a large model (for coding). This is the simplest setup and works for most individual developers.

How it works: Both agents route to localhost:11434, but LiteLLM selects different models based on the request context. The fleet dashboard monitors a single node with two loaded model aliases.

multi-node-cluster/ — Three-Node Local Fleet

For teams with multiple machines: a laptop, a Mac mini for heavy coding, and a GPU workstation for batch summarization tasks.

# examples/multi-node-cluster/fleet.yaml
project:
  name: dev-cluster
  gateway:
    provider: litellm
    host: 0.0.0.0
    port: 4000

nodes:
  macbook-pro:
    endpoint: http://localhost:11434
    tags: [local, fast]

  mac-mini-64gb:
    endpoint: http://192.168.1.50:11434
    tags: [heavy, coder, reviewer]

  gpu-workstation:
    endpoint: http://192.168.1.100:11434
    tags: [gpu, batch, summarizer]

models:
  small-coder:
    node: macbook-pro
    ollama_model: qwen2.5-coder:7b
    litellm_alias: claude-haiku-local

  heavy-coder:
    node: mac-mini-64gb
    ollama_model: qwen2.5-coder:32b
    litellm_alias: claude-sonnet-local

  batch-summarizer:
    node: gpu-workstation
    ollama_model: llama3.1:70b
    litellm_alias: llama-gpu-local

When to use: You have 2+ machines and want role-based routing — planning on fast models, coding on large models, summarization on GPU-accelerated hardware.

How it works: Each agent routes to a specific node's model. The fleet dashboard shows real-time health per machine: which nodes are online, which agents are hitting which endpoints, and any connection errors.

litellm-proxy/ — Generated LiteLLM Configuration

This directory contains the litellm_config.yaml that subagent-fleet generate produces from a fleet.yaml. It shows how LiteLLM routes requests to your Ollama models:

# examples/litellm-proxy/litellm_config.yaml (generated)
model_list:
  - model_name: claude-sonnet-local
    litellm_params:
      model: ollama_chat/qwen2.5-coder:32b
      api_base: http://192.168.1.50:11434
      api_key: ollama

router_settings:
  routing_strategy: simple-shuffle

How to use: Copy this to your project root and start LiteLLM:

cp examples/litellm-proxy/litellm_config.yaml .
litellm --config ./litellm_config.yaml --host 127.0.0.1 --port 4000

Then point Claude Code at the local gateway:

export OPENAI_API_BASE=http://localhost:4000
claude

claude-agents/ — Generated Agent Definitions

These are Claude Code agent definition files (*.md) generated by subagent-fleet generate. Each file teaches Claude Code a specific agent role with tools, prompts, and model routing.

Planner agent (planner.md) — Fast planning with small models:

---
name: planner
description: Use for planning, file discovery, task decomposition, and summarization.
model: claude-haiku-local
tools: Read, Grep, Glob
---
You are a fast local planning agent. Do not edit files.

Implementer agent (implementer.md) — Heavy coding with large models:

---
name: implementer
description: Use for implementation, bug fixes, refactors, and patch creation.
model: claude-sonnet-local
tools: Read, Grep, Glob, Edit, MultiEdit, Bash
---
You are a senior implementation agent. Make minimal, correct changes.

Reviewer agent (reviewer.md) — Quality checks with large models:

---
name: reviewer
description: Use after implementation to review diffs and tests.
model: claude-sonnet-local
tools: Read, Grep, Glob, Bash
---
You are a strict code reviewer. Focus on correctness, regressions, missing tests,
security issues, over-engineering, and maintainability.

How to use: After running subagent-fleet generate, these files appear in .claude/agents/ and teach Claude Code about your fleet agents:

subagent-fleet generate --config examples/fleet.yaml
# Creates .claude/agents/planner.md, implementer.md, reviewer.md

Complete Workflow Example

Here's a complete workflow using subagent-fleet:

# 1. Validate your fleet topology
$ subagent-fleet validate --config examples/multi-node-cluster/fleet.yaml
fleet.yaml is valid.

# 2. Discover what models are available on each node
$ subagent-fleet discover --config examples/multi-node-cluster/fleet.yaml
Fleet: dev-cluster

Node        Status    Models
macbook-pro Online    qwen2.5-coder:7b
mac-mini-64gb Offline   -
gpu-workstation Offline  -

# 3. Generate configuration files
$ subagent-fleet generate --config examples/multi-node-cluster/fleet.yaml
Generated: litellm_config.yaml
           .claude/agents/planner.md
           .claude/agents/implementer.md
           .claude/agents/reviewer.md

# 4. Start LiteLLM proxy
$ export LITELLM_MASTER_KEY="sk-local-dev"
$ litellm --config ./litellm_config.yaml --host 127.0.0.1 --port 4000

# 5. Open the fleet dashboard in your browser
$ subagent-fleet ui --config examples/multi-node-cluster/fleet.yaml
Dashboard running on http://127.0.0.1:8080

# 6. Monitor real-time health, routing, and traces
#    Node Health → Shows which machines are online/offline
#    Agent Routing → Shows which agent hits which model/node
#    Trace Stream → Live LiteLLM log tail
#    Warmup Progress → Model preload status

Common Patterns

Pattern 1: Fast Planning + Heavy Coding

Use a small, fast model for planning and a large, capable model for coding:

models:
  small-coder:      # Fast — lightweight, good for analysis
    ollama_model: qwen2.5-coder:7b
  heavy-coder:      # Large — capable at complex code changes
    ollama_model: qwen2.5-coder:32b

agents:
  planner:          # Uses fast model
    model: small-coder
  implementer:      # Uses large model
    model: heavy-coder

Pattern 2: GPU Offload for Batch Tasks

Offload summarization and documentation tasks to a GPU-accelerated node:

nodes:
  laptop:           # Small models, always available
    endpoint: http://localhost:11434
  gpu-box:          # Heavy inference, GPU-accelerated
    endpoint: http://192.168.1.100:11434

agents:
  summarizer:       # Routes to GPU node for batch processing
    model: gpu-model

Pattern 3: Single Node, Multiple Roles

All agents route to one machine — simplest possible setup:

nodes:
  local:
    endpoint: http://localhost:11434

agents:
  planner:
    model: small-coder      # Same node, different model alias
  implementer:
    model: heavy-coder      # Same node, different model alias

Next Steps

  • Copy an example and modify the fleet.yaml for your machines.
  • Run subagent-fleet generate to produce config files.
  • Open the dashboard with subagent-fleet ui to monitor your fleet.
  • Check out README.md for the full command reference.