01
Developer
Delegates code safely
Runs familiar agents through one CLI, previews the diff with dry-run, protects secrets, and limits how many files a task may touch.
Outcome: less risk to the working repository
CONTROL PLANE FOR AI CODING AGENTS
Agents write code.
VOLY runs the work.
Bring Claude Code, Codex, Cursor, and other tools into one managed process. VOLY routes tasks, verifies outcomes, protects file changes, and tracks cost.
- a provider failure does not kill the task
- changes are verified before the next step starts
- roles, files, and cost land in one report
WHY ADD A CONTROL LAYER
When one agent is no longer enough
A direct agent run is great for a one-off task. Daily development also needs recovery, guardrails, and evidence that the work is actually done.
×Credits run out and the task stops
✓VOLY switches executor and continues the run
×The agent says it is done
✓Plan gates verify files, git diff, and tests
×Nobody knows exactly what changed
✓The run report stores roles, files, diff, and outcome
×A premium model handles every step
✓Routing assigns the right model tier to each role
×Spend is scattered across providers
✓Tokens, cache hits, and cost share one telemetry trail
ONE CONTROL PLANE — THREE LEVELS
Who VOLY helps
Start locally on your own. Add orchestration and team Cloud as the workflow grows.
02
Tech lead
Splits complex work into accountable roles
Architect, developer, tester, and reviewer get separate models and checks. A step advances only after its result is verified.
Outcome: a managed chain instead of one giant prompt
03
Team
Shares the complete picture
Local and hosted runs enter one organization timeline with members, spend, status, files, and results in the Cloud dashboard.
Outcome: visibility without moving all compute to the cloud
How a task flies
One entry point — CLI, Web UI, or CI. From there, the route depends on task complexity.
voly run "implement auth refactor" --cwd /path/to/project
Multi-agent · hybrid A2A
The lead assigns tiers and skills. Implement roles write files via executors; review stays on chat. Results and cost flow into one run report.
Executor · fallback chain
claude-code
Anthropic
✗ billing
wrangler
Workers AI
✗ billing
opencode
free models
✗ billing
zen
free
✓ running
Out of billing — the next executor in the chain picks up the task. Every one of them writes files into --cwd. Use --dry-run to preview writes safely.
AIGateway.chat()
the only exit to models
DLP
Cache
Rate limit
Spend limit
BYOK
Provider
Telemetry
ONE TASK — ONE REPORT
A verifiable run, not a promise
VOLY records work by role and shows the evidence behind the final status. This is an illustrative run-report reading.
TaskFix the post-login redirect and add a regression test
✓ verified
architect
plan plus 3 acceptance checks
✓ verified
developer
4 files changed
✓ verified
tester
18 tests passed
✓ verified
reviewer
git diff accepted
4files
18/18tests
$0.84sample cost
readyoutcome
Illustrative report format; actual cost depends on the task and selected models.
CHOOSE YOUR RUNTIME
Direct agent, VOLY Local, or Cloud
The open core is complete: orchestration, safety, and cost control all run locally. Cloud adds hosting and the team surface.
| Capability | Direct agent | VOLY Local | VOLY Cloud |
|---|---|---|---|
| File-capable execution | yes | yes | yes |
| Multi-agent orchestration | — | yes | yes |
| Plan gates and safety policy | — | yes | yes |
| Billing fallback and cost report | — | yes | yes |
| Shared team history | — | — | yes |
| Roles, invites, and hosted runs | — | — | yes |
LOCAL
Local — keep control in your environment
Apache 2.0, runs on a laptop or your infrastructure, with your own keys and repositories.
Install Local →CLOUD
Cloud — give the team one operating surface
Organization, members, a shared local + hosted run history, spend, and BYOK aliases.
Open Cloud ↗Local run report & team cloud
Open-core Web UI: every run opens into a report — safety badges, hybrid role summary, touched files, dry-run diffs, pxpipe prompt images, tokens and cost. For the whole team: cloud.voly.codes shows shared org history, spend today, and hosted “Run in cloud”.
Orchestration
A lead orchestrator splits the task into roles and assigns each a model and skills. Implement roles write files; review stays on chat.
Plan gates
Steps only advance after verification — files, git, or tests. Not “the model said it was done.”
Safety
File writes are guarded: dry-run with diff preview, protected paths, max-files limit, git-based rollback.
Fallback
Billing fallback chain: claude-code → wrangler → opencode → zen. Out of credits — the task doesn't fail.
Telemetry & BYOK
Tokens, cost, and cache hits per run. Spend limits, cost policy — and provider keys in Cloudflare Secrets Store.
Open core + Cloud
Apache 2.0 core on your laptop. Team cloud is live: orgs, invites, shared run history, hosted runs, spend — features stay open, hosting is paid.
Executors
Who runs the task and what happens when billing runs out.
| Executor | Writes files | Billing | In the chain |
|---|---|---|---|
| claude-code | yes | Anthropic | 1st |
| wrangler | yes | CF Workers AI | 2nd |
| opencode | yes | free models → your own keys | 3rd |
| zen | yes | free | 4th (last resort) |
| cursor | yes | Cursor | standalone |
| deepseek / mimo | no — text only | API | outside the chain |
Skill & Plugin Marketplace
Install domain knowledge packs that agents use automatically. Skills teach methodology; plugins bundle tools. One command to install, active on the next run.
Find a skillGit packages
Multi-file skill packages (like PMBOK 6, design systems, company playbooks) install via git clone and are picked up instantly.
Lazy discovery
The lead orchestrator surfaces relevant skills from the marketplace mid-run — you see what's available for your specific task, not a generic catalogue.
One-click install
Install directly from the run result banner. The skill is active on the next run — no restart needed.
Live in marketplace:
— skills
— plugins
Savings you can see
VOLY counts every token: caching, routing, fallback, and pxpipe text→image compression turn into concrete numbers, not gut feelings.
voly savings
spent today
$4.20 / $20.00 limit
cache hits
62% → saved $6.85
model routing
premium → cheap: $3.10
pxpipe artifacts
prompt images saved per task
task re-runs
8 tasks from cache: $0.00
total this week
saved $41.70
* example output — numbers depend on your tasks
Quick start
A full control plane running locally in a couple of minutes. Python 3.10+. Keys via .env or BYOK in Cloudflare Secrets Store.
git clone https://github.com/voly-codes/voly.git && cd voly
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[ui,dev]"
voly init && voly ui
voly pxpipe start # optional: token-saving Claude Code proxy
voly run "fix a bug" --cwd ~/my-project --dry-run
# local dashboard at localhost:7788 — team cloud at cloud.voly.codes
Higher together
Build and run agents open-core on your machine — or invite the team on cloud.voly.codes.
Orchestration
A complex task never goes to a single agent — it is decomposed into roles, each executed by a model of the right tier (hybrid multi-agent).
- TaskDecomposer splits the task: architect → developer → tester → reviewer → devops.
- The lead orchestrator (a premium model) assigns each role a tier — premium, standard, or cheap — plus skills from the registry.
- Hybrid path: implement roles run file-capable executors under --cwd; reviewer and chat roles stay on AIGateway.
- A tier resolves to a concrete model from a live pool: providers are filtered by a health checker.
- Role outputs, cost, and files land in the run report in the Web UI — including live CLI tasks while they run.
voly run "implement auth refactor" --cwd /path/to/project
Plan gates
Good plans are not enough if the agent freestyles. VOLY turns a plan into a state machine with hard gates.
- Each step has a status: pending → running → verified (or failed).
- The next role starts only after prior steps are verified — evidence over self-report.
- Acceptance checks: command, files_exist, git_diff, output — fail closed on unknown types.
- Modes: shadow (log and soft-open) or active (hard gate). Multi-agent A2A can use the same rules.
- CLI: voly plan run | criteria | suggest — draft checks from free text or ProjectScanner.
voly plan run plan.yaml --mode active --cwd /path/to/project
Safety
Letting an agent write into a real repo needs a safety net — VOLY ships one in the open core.
- --dry-run runs the full executor path, then rolls changes back and keeps a diff preview in the result.
- Protected paths block writes to secrets and env files (.env*, keys, credentials) by policy.
- Max-files limit stops a runaway agent from touching half the monorepo in one run.
- Touched files are detected from content (not only git dirty-before), so clean tracked files modified mid-run still show up.
- The Web UI run report surfaces safety badges, hybrid summary, files, and dry-run diffs.
voly run "refactor the config loader" --executor claude-code --cwd ~/my-project --dry-run
Fallback
When the current executor runs out of money, VOLY automatically hands the task to the next one in the chain.
- The chain: claude-code (Anthropic) → wrangler (CF Workers AI) → opencode (free models) → zen (free).
- billing_error = true → next executor; every executor in the chain writes files into --cwd.
- Inside the AI Gateway: model-level fallback and provider health checks.
- Sub-agents are deterministic (temperature = 0) and the cache is persistent: re-running the same task costs $0.
voly status
Telemetry & BYOK
Every run leaves a TaskEvent: who executed it, which model, how many tokens, how much money, and which local artifacts were produced. Keys do not have to live in every machine’s .env.
- A daily spend limit and a per-task cost policy keep spending under control.
- Gateway pipeline: DLP → Cache → Rate limit → Spend limit → Provider → Telemetry.
- BYOK: store provider keys in Cloudflare AI Gateway / Secrets Store; the gateway resolves them per request.
- Web UI: Provider keys page, analytics (daily, by_agent, by_model, by_provider), local task artifacts, and voly savings.
- pxpipe can route Claude Code through a local token-saving proxy and save rendered prompt PNGs into the task report.
- voly savings shows how much caching, routing, fallback, and compression saved.
voly savings
Open core + Cloud
VOLY is not yet another agent — it is an open control plane between the developer and the agents.
- Open core (public repo): orchestration, hybrid multi-agent, fallback chain, safety policy, FinOps, local CLI + Web UI, BYOK in your Cloudflare account.
- Cloud (live MVP at cloud.voly.codes): register/login, orgs & invites, shared org run history (local + hosted), spend rollup, BYOK aliases, Run in cloud.
- Local agent can report finished runs to the org when linked — one team timeline, compute stays on the laptop if you want.
- Wraps Claude Code, Cursor, Codex, Zen, OpenCode, and more under --cwd.
- Providers: Anthropic, OpenAI, Google, DeepSeek, Workers AI, Cloudflare AI Gateway. Contributions via DCO.
pip install -e ".[ui,dev]" && voly init