cv-orchestrate

Fleet orchestration daemon for CV-Agent. Deploy, supervise, and route AI agents across machines.

The Problem

You have agents. You don't have a fleet. Every cva agent session is a manual SSH + terminal process that dies when the shell closes. No auto-restart, no health monitoring, no remote deployment, no capability-based task routing.

cv-orchestrate solves this with two components:

1. cvod — A daemon that runs on each machine as a systemd service, spawning and supervising agent processes per a YAML manifest
2. Fleet API — CV-Hub extensions for remote machine management, agent deployment, and intelligent task routing

Architecture

┌─────────────────────────────────────────────────────────┐
│                   CV-Hub (Control Plane)                  │
│                                                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐ │
│  │ Task Router │  │  Machine   │  │  Fleet Dashboard   │ │
│  │ (affinity,  │  │  Registry  │  │  (health, logs,    │ │
│  │  capability │  │            │  │   cost, metrics)   │ │
│  │  routing)   │  │            │  │                    │ │
│  └──────┬──────┘  └─────┬──────┘  └────────────────────┘ │
└─────────┼───────────────┼────────────────────────────────┘
          │               │
     ┌────┴────┐     ┌────┴────┐     ┌──────────┐
     │ primary │     │  aux-1  │     │   gpu-1  │
     │  cvod   │     │  cvod   │     │  cvod    │
     │         │     │         │     │          │
     │ agent-a │     │ agent-c │     │ trainer  │
     │ agent-b │     │ agent-d │     │          │
     │ mcp-svc │     │ mcp-svc │     │          │
     └─────────┘     └─────────┘     └──────────┘

Quick Start

# Install
npm install -g @controlvector/cv-orchestrate

# Initialize on a machine
cvod init --name aux-1 --role auxiliary

# Edit agent manifest
vim /etc/cvod/agents.yaml

# Start daemon
sudo systemctl enable cvod
sudo systemctl start cvod

# Or run foreground for testing
cvod start --foreground

Agent Manifest

# /etc/cvod/agents.yaml
machine:
  name: aux-1
  role: auxiliary
  tags: [build, network]
  hub_url: https://api.hub.controlvector.io

agents:
  - name: example-mcp
    repo: myorg/example-mcp
    workspace: /home/user/projects/example-mcp
    auto_approve: true
    restart: always        # always | on-failure | never
    max_restarts: 10       # per hour
    backoff_base_ms: 1000
    env_file: ~/.env.example-mcp

  - name: scheduled-job
    repo: myorg/scheduled-job
    workspace: /home/user/projects/scheduled-job
    auto_approve: true
    restart: always
    schedule: "0 */6 * * *"  # cron-style scheduled runs
    env_file: ~/.env.scheduled-job

CLI Commands

cvod init           # Initialize machine, create manifest template
cvod start          # Start daemon (reads agents.yaml, spawns agents)
cvod stop           # Graceful shutdown of all agents
cvod status         # Show all agents, PIDs, uptime, health
cvod logs <agent>   # Tail agent logs
cvod restart <name> # Restart specific agent
cvod deploy <repo>  # Clone repo + add agent to manifest
cvod remove <name>  # Stop agent + remove from manifest
cvod register       # Register machine with CV-Hub fleet API
cvod unregister     # Remove machine from fleet

Fleet API (CV-Hub Extensions)

GET    /api/v1/fleet/machines          List registered machines
GET    /api/v1/fleet/machines/:id      Machine details + agents
POST   /api/v1/fleet/machines/:id/cmd  Send command to machine daemon
GET    /api/v1/fleet/agents            List all agents across fleet
POST   /api/v1/fleet/deploy            Deploy agent to machine
DELETE /api/v1/fleet/agents/:id        Stop + deregister agent
GET    /api/v1/fleet/health            Fleet-wide health summary

Task Routing

CV-Orchestrate extends CV-Hub's task dispatch with machine affinity:

# Task routing rules (in CV-Hub config)
routing:
  rules:
    - match: { repo: "myorg/example-app", requires: ["toolchain-x"] }
      prefer: primary
    - match: { task_type: "deploy", requires: ["gpu"] }
      prefer: gpu-*
    - match: { tag: "build" }
      prefer: aux-1
  fallback: any-available

License

MIT. See LICENSE. Copyright (c) Control Vector LLC.