FleetFuse (fleet-fuse)

Bring the AI engines you already use online as one privacy-gated, cost-aware fleet.

FleetFuse is maintained by Renn Labs as a standalone OSS project. Visibility changes, release tags, package publishing, and any personal fork or mirror remain explicit human-gated release steps.

fleet-fuse is a Python CLI and MCP server for AI development work. Give it one task; it decomposes the work, routes each sub-task to a specialist persona, fans out across configured engines, then synthesizes one result. High-sensitivity work stays on first-party CLIs. External pools are opt-in, sensitivity-gated, redacted, and budget-aware.

Zero-key quickstart

These commands make no live model calls and require no API keys:

git clone https://github.com/Renn-Labs/FleetFuse.git
cd FleetFuse
python3 setup.py --doctor --offline-ok
python3 fleet-fuse.py --list-agents
scripts/onboarding-smoke.sh

The smoke script runs compile-free offline checks, selftests, privacy/billing contracts, scrubber fixtures, and a dry-run route preview.

Real runs

Guided setup writes ~/.config/fleet-fuse/env with mode 0600; real environment variables still override it.

python3 setup.py
python3 setup.py --doctor
python3 setup.py --heal --dry-run --offline-ok

Run with first-party CLIs only:

python3 fleet-fuse.py "review this repository for release blockers" --sensitivity high

Run with the OpenRouter OSS overflow pool enabled:

python3 fleet-fuse.py "plan and test a CLI feature" --sensitivity medium --enable-external --yes-metered

Run the verified research loop:

python3 fleet-fuse.py "research 50 EV companies" --mode verify-loop --items 50 --enable-external --yes-metered

Run the optional billed Viapi connectivity check:

python3 fleet-fuse.py --viapi-smoke

Setup

python3 setup.py            # guided: detects engines, toggle each on/off, capture OpenRouter key

It writes ~/.config/fleet-fuse/env (chmod 600) — loaded automatically on every run. Re-run any time to change which engines are on or rotate the key.

Check readiness anytime (OS, Python, engines, deps, key) with remediation hints:

python3 setup.py --doctor

Inspect providers, auth, selected models, local caps, and disable markers without paid model calls:

python3 setup.py --providers --json
python3 fleet-fuse.py --providers --json
python3 fleet-fuse.py --list-openrouter-models

Preview safe local repairs for a broken FleetFuse install:

python3 setup.py --heal --dry-run --offline-ok --json

Apply only reversible local repairs:

python3 setup.py --heal --offline-ok

--heal is designed for agentic coding harnesses fixing a local FleetFuse instance. It can create or normalize the local config file, restore private config permissions, normalize harness and Grok presets, and disable unavailable pools until the user installs/logs into the relevant engine. It does not invent secrets, clear provider billing/quota markers, make paid live calls, edit host MCP configs, touch GitHub remotes, push, tag, or release.

Guided by an AI session (Claude Code / Codex / Grok Build): ask the user which engines to enable and for an OpenRouter key, then run the non-interactive form:

python3 setup.py --non-interactive --enable grok,codex,openrouter,viapi \
  --openrouter-key sk-or-... --viapi-key vi_live_... [--external-preference viapi] \
  [--openrouter-models qwen/qwen3.7-max,moonshotai/kimi-k2.7-code] \
  [--openrouter-monthly-usd 25] [--viapi-monthly-usd 25] [--jimmy-models ...] [--install-deps]

Why

• Cost-class cascade — saturate fixed-cost subscriptions (Grok, then Codex) before spilling to metered OpenRouter. ≤~12 medium sub-tasks never touch the paid pool, and live metered routes require --yes-metered or an interactive YES.
• Agent-aware routing — a Rust sub-task runs as rust-pro, a quant sub-task as quant-analyst (bundled persona library; auto-matched or explicitly tagged).
• Fail-closed redaction — external user/task payloads are scrubbed before dispatch; a secret that survives scrubbing drops the sub-task rather than leaking it. Specialist system personas are local bundled prompts, not user secrets.
• Self-verifying loop — --mode verify-loop: plan → swarm → verify each result against a checklist → requeue failures until the pass is clean.
• Multi-session safe — run it from many shells/projects at once: outputs are namespaced per run, and a cross-session semaphore caps total Grok/Codex/OR workers box-wide.

Requirements

• Python 3.10+ (stdlib only for the core; local gates cover 3.10-compatible syntax and the release machine currently runs 3.12).
• Engine access — defaults to the peer CLI (peer grok / peer codex), a version-drift- resistant bridge used by the local OMX setup. This repository does not vendor peer. No peer? Set FLEET_GROK_CMD="grok" and FLEET_CODEX_CMD="codex exec" (prompt is fed on STDIN). Grok/Codex must be logged in.
• Grok Build preset — set FLEET_GROK_PRESET=build to use xAI Grok Build headless mode (grok -p "{prompt}") as the Grok worker path. Use FLEET_GROK_CMD for custom wrappers.
• OpenRouter API key for the OSS pool (captured by setup.py).
• Optional: pip install -r requirements.txt (Presidio, Chroma, rich, cryptography) — all degrade gracefully if absent. Chroma skill indexing is disabled unless FLEET_ENABLE_CHROMA=1 because first use can download embedding assets.

Configure (env — setup.py writes these)

var	default	purpose
OPENROUTER_API_KEY	—	OSS-swarm pool
FLEET_OPENROUTER_MODELS	auto OSS allowlist	comma-separated OpenRouter model IDs to pin
FLEET_OPENROUTER_MONTHLY_USD	—	client-side monthly $ cap for OpenRouter; calls reserve estimated spend before dispatch
VIAPI_API_KEY	—	Viapi billed gateway pool (vi_live_…); LOW tier only
FLEET_VIAPI_BASE	…api.viapi.ai/v1/proxy	Viapi base URL (includes /v1/proxy)
FLEET_EXTERNAL_PREFERENCE	openrouter	preferred metered pool: openrouter | viapi
FLEET_HARNESS	auto	preferred controlling harness for MCP dispatch: auto | codex | claude | grok
FLEET_DISPATCH_ENGINE	auto	optional direct worker-engine override for dispatch_agent
FLEET_VIAPI_MONTHLY_USD	—	client-side monthly $ cap for the billed pool; calls reserve estimated spend before dispatch
FLEET_DISABLED_POOLS	—	engines turned OFF, e.g. codex,jimmy
FLEET_AGENTS_DIR	./agents	specialist persona library
FLEET_GROK_PRESET	peer	Grok worker preset: peer | build | raw
FLEET_GROK_CMD / FLEET_CODEX_CMD	peer grok / peer codex	engine commands
FLEET_GLOBAL_GROK / _CODEX / _OR	8 / 4 / 24	total workers across ALL sessions
FLEET_JIMMY_MODELS	(empty)	optional low-tier LiteLLM models; pool inert unless set
FLEET_RETURN_MODE	summary	fanout handoff shape: summary | manifest | full
FLEET_MAX_RETURN_CHARS	1800	max summary chars per worker returned to a parent harness
FLEET_SYNTH_MAX_CHARS_PER_RESULT	2400	max worker-card chars fed into standalone synthesis
FLEET_MCP_MAX_RETURN_CHARS	1800	max single-agent MCP handoff summary chars

Usage

python3 fleet-fuse.py --list-agents                       # specialist catalog
python3 fleet-fuse.py --providers --json                  # redacted provider/auth/model/cap status
python3 fleet-fuse.py "review this repository" --sensitivity medium --enable-external --yes-metered
python3 fleet-fuse.py "research 100 EV companies" --mode verify-loop --items 100 --enable-external --yes-metered
python3 fleet-fuse.py --mode fanout --subtasks '[{"task":"…","agent":"rust-pro"}]' --enable-external --yes-metered
python3 fleet-fuse.py --dry-run "..."                     # preview routing, zero external calls
python3 fleet-fuse.py --viapi-smoke                       # optional billed live Viapi smoke

--no-redact is local/first-party only. If combined with --enable-external, external pools are disabled before dispatch.

Live --mode verify-loop requires the Claude CLI with the configured Opus verifier. The offline selftest uses deterministic seeded records and does not require Claude.

Context-Safe Handoffs

Fleet Fuse defaults to artifact-backed worker handoffs so the parent harness does not ingest every raw worker transcript. fanout returns compact cards containing summary, handoff.artifact_path, raw_sha256, raw byte counts, and compression telemetry. Raw output is written under per-run worker artifact folders in runs/ and can be opened only when the orchestrator needs detail.

Use --return-mode summary for normal orchestration, --return-mode manifest for the lowest-token path, and --return-mode full only for local debugging. MCP dispatch_agent follows the same principle: it returns a bounded handoff card plus a raw artifact pointer instead of unbounded tool content.

Sensitivity tiers

--sensitivity	engines	use for
high	Grok + Codex only (no external)	private / sensitive
medium	+ OpenRouter OSS (strict routing request: data_collection=deny, zdr=true, no fallback outside filter)	normal
low	+ OpenRouter OSS + Viapi (billed) + jimmy if configured	public / vanilla

External pools require --enable-external and a permitting tier; high never reaches them. OpenRouter model resolution is allowlisted to OSS-family prefixes (DeepSeek / Kimi / Qwen / GLM / MiniMax) — never Anthropic, xAI, OpenAI, or Codex aliases. OpenRouter is inert until OPENROUTER_API_KEY is configured. Use FLEET_OPENROUTER_MODELS or --or-models to pin specific allowed model IDs, --list-openrouter-models to inspect allowed catalog rows, and --providers --json to verify key status, model validation, local spend, and disable markers before dispatch. Viapi (your billed gateway) is LOW-sensitivity only until it enforces per-request ZDR; set FLEET_EXTERNAL_PREFERENCE=viapi to prefer it over OpenRouter (which stays the fallback + medium engine). OpenRouter and Viapi calls reserve estimated spend before dispatch, update local ledgers with actual response cost when providers return it, and write local disable markers after terminal budget/quota errors. Clear ~/.config/fleet-fuse/openrouter-disabled.json or ~/.config/fleet-fuse/viapi-disabled.json only after the provider-side billing/quota/auth issue is resolved. Client-side caps are safeguards, not provider billing guarantees.

User Responsibility Notice

FleetFuse orchestrates model providers and coding agents; it does not guarantee that any LLM output is correct, safe, complete, or production-ready. LLMs can fabricate facts, miss security issues, change behavior across model/provider releases, and take actions that consume tokens or provider quota when you authorize live external routing.

You are responsible for the API keys you configure, provider terms, data sent to each provider, model selection, privacy posture, token usage, agent fan-out, retries, and resulting spend. Run --dry-run and --providers --json before live metered runs, set provider-side limits when available, and review outputs before relying on them for production, legal, financial, security, or operational decisions. FleetFuse is provided as OSS tooling under the MIT license and is not legal, financial, security, or professional advice.

MCP server

fleet_mcp.py exposes dispatch_agent(agent, task), fleet_fuse(task, sensitivity, ...), and provider_status(json=true) to any MCP client. Codex can be the main harness:

codex mcp add fleet -- python3 /abs/path/fleet_mcp.py

Claude Code and Grok Build can register the same stdio server in their MCP config. In MCP mode, the host agent remains the orchestrator and calls fleet-fuse for specialist dispatch or full fleet fan-out. Set FLEET_HARNESS=codex|claude|grok when you want the MCP server to prefer a specific dispatch engine; leave it as auto to use the first available compatible CLI. For external metered routing through MCP, the caller must pass yes_metered=true after the user has explicitly accepted provider privacy/cost tradeoffs for that run.

Codex Native Subagents

Fleet Fuse complements Codex native subagents; it does not replace them. Use native Codex subagents when you want Codex to own the whole parallel workflow in the current repo. Use Fleet Fuse when you want a harness-neutral dispatch layer with explicit sensitivity tiers, provider routing, reusable specialist personas, budget controls, and the same MCP server callable from Codex, Claude Code, or Grok Build.

Offline CI

The optional GitHub Actions workflow at .github/workflows/offline.yml is keyless and offline-only. It runs compile checks, contract tests, onboarding smoke, and launch hazard scans for this standalone repository on Python 3.10 and 3.12. Live engine readiness still belongs to python3 setup.py --doctor on the release machine.

MCP Roadmap

The current MCP server is intentionally tool-only: dispatch_agent, fleet_fuse, and provider_status are the stable surface. Resource and prompt endpoints are valid future additions for richer policy, run history, and reusable launch workflows, but they should stay out of the public API until the tool contracts are stable.

Files

file	role
setup.py	guided installer (engine on/off, key capture)
fleet-fuse.py	orchestrator; modes fuse / fanout / verify-loop
fleet_scrub.py	redaction + leak-block (fail-closed)
fleet_agents.py	specialist registry + matcher
fleet_verify.py	self-verifying loop
fleet_mcp.py	stdio MCP server
fleet_logo.py	gradient wordmark
agents/	bundled specialist personas (see NOTICE)
cli-freshness.sh	optional weekly engine-CLI update + bridge smoke-test

Platforms & troubleshooting

Run python3 setup.py --doctor for a readiness check. Run python3 setup.py --heal --dry-run --offline-ok --json when an agent needs a machine-readable repair plan for a broken local instance.

• Linux / macOS — fully supported.
• Windows — the core runs; the cross-session limiter (fcntl) gracefully no-ops (per-session caps still apply). peer/grok/codex are Unix-oriented — use WSL, set FLEET_GROK_CMD / FLEET_CODEX_CMD to native commands, or run OpenRouter-only. Use py -3 / python instead of python3. chmod 600 is weaker on NTFS — keep the config private.
• Python 3.10+ required (doctor checks); core is stdlib-only.
• Engines unreachable — install peer or set FLEET_GROK_CMD/FLEET_CODEX_CMD; the OpenRouter pool needs OPENROUTER_API_KEY. high sensitivity needs grok or codex (no external) — key-only setups should use medium/low.
• No colors / garbled banner — set NO_COLOR=1 or use a truecolor terminal (Windows Terminal, iTerm, modern xterm).
• Stronger PII redaction — pip install presidio-analyzer + python -m spacy download en_core_web_lg; without it a stdlib regex+entropy scrubber is used.

License

MIT (LICENSE). Bundled personas under agents/ are vendored from wshobson/agents (MIT) — see NOTICE.