AI Agent Control Plane · Multi-Agent Orchestration · Billing Fallback Chain · DSPy · FinOps · A2A · AG-UI · Cloudflare AI Gateway

English · Русский

VOLY — Control Plane for AI Agents

VOLY wraps Claude Code, Cursor, Codex, Zen and other AI agents so you can run them cheaper, safer, and with full measurability.

VOLY is not another AI agent. It is a self-hosted control plane between the developer and the agents:

• routes tasks across executors with an automatic billing fallback chain;
• decomposes complex work into sub-agents (architect → developer → tester → reviewer → devops), where a strong lead orchestrator assigns model tiers and skills;
• guards file writes — dry-run with diff preview, protected paths, max-files limit, git-based rollback;
• controls spend via Cloudflare AI Gateway, spend limits, and cost policy;
• reduces tokens with a persistent cache, Headroom, model routing, and determinism;
• collects telemetry per run and surfaces metrics in the Web UI;
• supports DSPy as an optional optimization layer;
• stays project-agnostic — the target project is passed via --cwd or VOLY_PROJECT_CWD.

Why VOLY, and not just a single agent?

Claude Code, Cursor, and Codex are excellent executors. VOLY is the layer
above them — it exists because running agents daily raises questions a
single CLI cannot answer:

If all you need is "write code from a prompt" — use an agent directly. VOLY
pays off when agents become part of the daily workflow and you need
economics, control, and reports.

3-minute demo

voly init                                   # config + hooks
voly run "fix the auth redirect bug" \
    --executor claude-code --cwd ~/my-project
# → the executor writes files; if it hits a billing error the chain
#   falls through to the next executor; cost and touched files land
#   in the run report

voly run "refactor the config loader" \
    --executor claude-code --cwd ~/my-project --dry-run
# → same run, but every file change is rolled back afterwards;
#   the diff preview is kept in the result

voly ui                                     # web dashboard on :7788

A complex request ("redesign auth, add tests, review it") goes multi-agent
automatically: the lead model assigns roles and tiers, implement roles write
files through executors, the reviewer stays on chat — the report shows
role / model / cost / files per agent.

Open core vs Cloud

The open core is complete and self-hosted. The paid tier sells hosting and
team management — not core features.

How it works

A task from the web UI, CLI, or CI enters a single entry point and takes one of two paths:

Developer / Web UI / CLI / CI
              ↓
       VOLY Entry Point
              ↓
        ROUTE (task analysis)
        ┌─────┴───────────────────────────┐
        │                                 │
   complex,                         simple code
   ≥2 capabilities                  generation (1 flag)
        │                                 │
        ▼                                 ▼
  PIPELINE · MULTI-AGENT            EXECUTOR PATH
  (A2A local)                       (file-capable)
        │                                 │
  Lead orchestrator                 executor.run(task, cwd)
   ├─ tier + skills per role        Billing Fallback Chain:
   ├─ architect → developer         claude-code → wrangler → opencode → zen
   ├─ tester / reviewer / devops          │
   └─ each via AIGateway.chat()           │
        │                                 │
        └────────────┬────────────────────┘
                     ▼
              AIGateway.chat()
DLP → Cache → Rate limit → Spend limit → Provider → Telemetry

Non-code-generating text tasks go through a single model call on the same pipeline path.

AIGateway.chat() is the only exit point to models. Pipeline, sub-agents, DSPy, and runtimes all go through it — cache, DLP, spend limits, fallback, and telemetry stay consistent.

Smart dispatch (POST /api/run, executor=pipeline):

• complex multi-capability task (≥ a2a.min_flags_for_dispatch flags from code-gen / review / testing / deployment, or complexity=high) → stays in the pipeline and runs multi-agent;
• simple code task → promoted to executor=claude-code with cwd from config / VOLY_PROJECT_CWD (so files are actually written);
• text task → single model call.

Multi-agent orchestration (A2A local)

When a task enters multi-agent mode (a2a.execution_mode=local, default):

1. TaskDecomposer splits the task into roles with dependencies (architect → developer → tester → reviewer → devops).
2. Lead orchestrator — a strong (premium) model scores the task and assigns each role a model tier (premium | standard | cheap) and skills from the registry. On lead LLM failure — deterministic fallback.
3. Tier → concrete (model, provider) from a live pool filtered by ProviderHealthChecker:
   • strong: anthropic, cloudflare-dynamic
   • weak/cheap: workers-ai, deepseek, opencode-zen, mimo, omniroute
4. Sub-agents run in-process via AIGateway.chat() in dependency order; prior role outputs are passed forward.
5. Merge → TaskEvent with a2a_assignments (role / tier / model / skills / tokens / cost / cache_hit). Visible in the Web UI (“Multi-agents” panel).

Repeat savings: sub-agents are deterministic (temperature=0), and the gateway cache is persistent (on disk) — an identical re-run hits the cache across the whole chain (cost → $0). Skip a provider (e.g. out of credits): VOLY_A2A_EXCLUDE_PROVIDERS=anthropic.

Quick start

git clone https://github.com/voly-codes/voly.git
cd voly
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[ui,dev]"
cp .env.example .env       # add API keys
voly init
voly status

Web UI (dev):

# backend API (FastAPI) — :7788
python3 -m uvicorn voly.web.server:create_app --factory --host 127.0.0.1 --port 7788
# UI dev server (Vite) — :5173, proxies API to :7788
cd ui && npm install && npm run dev

Single process (production, serves the built UI on :7788):

cd ui && npm run build && cd ..
voly ui

Pipeline runner for CF agent workers over a tunnel — separate service on :9202:

voly serve

DSPy (optional):

pip install -e ".[dspy,dev]"
voly dspy status

Web UI auth (optional)

By default the API is open on localhost. Before exposing the UI/API on a network, enable JWT:

export VOLY_AUTH_ENABLED=true
export VOLY_JWT_SECRET='long-random-secret-at-least-32-chars'
export VOLY_AUTH_USERS='admin:change-me'

See docs/backend/api.md for login and protected routes.

Billing fallback chain (executor path)

If the current executor runs out of budget, AgentRunner walks the chain:

claude-code  →  wrangler  →  opencode  →  zen
(Anthropic)    (CF Workers)  (OpenCode)   (free / last resort)

ExecutorResult.billing_error = True → next executor. All of these can write files under --cwd.

Executors

voly run "implement auth refactor" --executor claude-code --cwd /path/to/target-project

For automatic selection use the Web UI or voly match.

AI Gateway

AIGateway.chat() is the single model exit. Middleware: DLP → Cache → Rate limit → Spend limit → Routing → Provider.

• Persistent cache — responses are stored on disk (ai_gateway.cache_persist_dir, default .voly/gateway_cache), so repeats hit cache across requests and restarts.
• Spend on success only — failed provider calls do not inflate the daily budget.
• Providers: anthropic, openai, google, deepseek, workers-ai, cloudflare-dynamic, opencode-zen, mimo, omniroute (self-hosted OpenAI-compatible gateway, opt-in).
• Gateway tab metrics come from telemetry (real requests / tokens / cost / by_provider / by_model / spent_today), not a fresh empty instance.

The CF Worker (cf-workers/agent/src/infer.ts) routes inference through the CF AI Gateway route schema (CF_ACCOUNT_ID + CF_AIG_TOKEN, POST /infer) or env.AI.run() fallback.

Web UI

Svelte 5 SPA with hash routing: #/tasks, #/gateway, #/telemetry, #/dspy plus Cloudflare and Skill Marketplace drawers.

DSPy — optional optimization layer

voly dspy status
voly dspy dataset build
voly dspy compile --agent reviewer
voly dspy promote code-review.v2 --tag production

Configuration

# voly.yaml
default_cwd: ""              # target project path (or VOLY_PROJECT_CWD)

ai_gateway:
  provider: cloudflare
  cache_enabled: true
  cache_persist_dir: .voly/gateway_cache   # disk cache; empty → in-memory only
  spend_limit_usd_per_day: 20.0

a2a:
  enabled: true
  auto_dispatch: true         # auto multi-agent for complex tasks
  min_flags_for_dispatch: 2   # capability-flag threshold
  execution_mode: local       # local (lead + sub-agents) | federation (remote)
  lead_model: ""              # lead model; empty → premium from healthy pool

auth:
  enabled: false              # set true + VOLY_JWT_SECRET before network exposure
  cors_origins:
    - "http://localhost:7788"
    - "http://localhost:5173"

cost_policy:
  max_task_cost_usd: 2.0

dspy:
  enabled: false
  mode: shadow

Key env vars:

ANTHROPIC_API_KEY=sk-ant-...              # claude-code / premium tier
OPENCODE_API_KEY=...                      # zen / opencode-zen
CLOUDFLARE_ACCOUNT_ID=...                 # CF AI Gateway + Workers AI
CLOUDFLARE_API_TOKEN=...
CF_AIG_TOKEN=...                          # CF Dashboard → AI Gateway → Settings
VOLY_PROJECT_CWD=/path/to/proj            # default cwd for executor and UI
VOLY_A2A_EXCLUDE_PROVIDERS=               # e.g. "anthropic" — hide from tier pool
VOLY_AUTH_ENABLED=false
VOLY_JWT_SECRET=
VOLY_AUTH_USERS=admin:change-me
OMNIROUTE_BASE_URL=http://localhost:20128 # if using the OmniRoute adapter

BYOK — provider keys in Cloudflare (optional)

With ai_gateway.byok_enabled: true, keys for anthropic / openai /
google-ai-studio / deepseek are stored in CF Secrets Store and resolved by
the AI Gateway per request — no provider keys in .env, only CF_AIG_TOKEN.
See docs/backend/ai-gateway.md § BYOK (Store Keys).

Hosted catalog & marketplace (optional, opt-in)

You can use the official hosted skill catalog / marketplace instead of
deploying your own workers from cf-workers/:

CF_WORKER_CATALOG_URL=https://catalog.voly.codes
CF_WORKER_MARKETPLACE_URL=https://marketplace.voly.codes

voly setup offers to write these for you. Privacy note: catalog/skill
queries then go to those workers; nothing is sent unless you opt in.

Core commands

voly run <task>                        # pipeline (→ multi-agent when complex)
voly run <task> --executor claude-code --cwd /path/to/project
voly match <task>                      # pick agent / executor / model
voly status                            # component health
voly savings                           # savings report
voly ui                                # web dashboard (FastAPI + Svelte) :7788
voly serve                             # pipeline HTTP runner :9202

voly registry agents | skills          # agent / skill registry
voly model list                        # models and pricing
voly ai-gateway status                 # AI Gateway status
voly spend status                      # current daily spend
voly dspy status                       # DSPy programs + mode
voly cloud login                       # link device to a VOLY Cloud org (shared run history)

CI and tests

pytest tests/test_dspy_runtime_smoke.py     # required after changes
pytest tests/test_multiagent_smoke.py       # multi-agent (mock gateway)
pytest tests/test_web_auth.py               # JWT auth baseline
pytest tests/ -q                            # full suite

GitHub Actions: base install (Python 3.10–3.14), import smoke without/with DSPy, runtime smoke tests.

Do not commit

.voly/events/  .voly/dspy/  .voly/reports/  .voly/gateway_cache/
.venv/  ui/node_modules/  voly/web/static/

Documentation

Contributing & License

Contributions welcome — see CONTRIBUTING.md (DCO, rules, open-core boundaries). Licensed under Apache 2.0.