Orca – Painel de Controle MCP para Orquestração Multi-Agente
alex2481kobe/orca
Orquestre agentes de IA em paralelo com um painel de controle local seguro
Ver no GitHubPlano de controle local-first para coordenar múltiplos agentes de codificação (Codex, Claude, APIs) em workflows distribuídos. Oferece um dashboard unificado, acesso via desktop, CLI, web, PWA e celular, com auditoria, capturas de tela e gerenciamento de capacidade.
Instalação
npx convez-ai alex2481kobe/orca1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenar múltiplos agentes IA em tarefas de codificação complexas
- Gerenciar backlog de trabalho e lanes de execução paralelos
- Monitorar e auditar workflows de agentes de qualquer dispositivo
- Integrar Codex, Claude e APIs customizadas em pipeline unificado
Veredito

Ferramenta madura e bem arquitetada para quem já roda agentes de codificação e precisa de orquestração real. Foco em local-first e privacidade é raro e valioso; exige familiaridade com MCP, múltiplos modelos e CLI para aproveitar todo potencial.
README
A tradução para o português deste README ainda está na fila.
Orca
Orchestrate fleets of Codex, Claude, and API-backed coding agents from MCP, CLI, desktop, web, or phone.
Orca is a local-first MCP control plane for multi-agent coding workflows. One agent can coordinate a fleet of executor lanes across your projects: Codex can manage Claude lanes, Claude can manage Codex lanes, and either can fan work out to API-backed or custom CLI lanes while Orca enforces the workflow, captures evidence, and keeps secrets on your workstation.
Use the surface that fits the moment: the web/PWA dashboard, the Tauri desktop
app, your phone over private Tailscale, an MCP client inside Codex or Claude, or
the orca-agent CLI from any shell-capable agent. The current validated setup is
a macOS workstation plus phone access; Windows and Linux are intended future
validation targets.
Why Orca
You're already running coding agents. The problem is coordination: which agent is on which task, in which project, is it done, is it any good, and who is allowed to spawn the next lane? Orca is the local control plane for that.
- 🧭 One command center, many entry points. Use the dashboard, desktop app,
phone, MCP, or
orca-agentCLI. Every surface talks to the same server-side workflow and audit state. - 🔁 Cross-agent orchestration. Let Codex manage a backlog and spawn Claude executor lanes, let Claude coordinate Codex lanes, or mix in API-backed agents when a task fits a model provider better than a terminal agent.
- 🤖 Bring your own agents, with clear support boundaries. Codex and Claude are the primary tested CLI/in-app orchestration paths. Orca also has wired profiles for Gemini CLI, Composer, custom CLIs, and OpenAI-compatible / Gemini / Kimi / DeepSeek / OpenRouter APIs; see the run-mode docs for what is tested versus experimental.
- 🧩 Real orchestration, not a wrapper. Orchestrator → executor → auditor roles, capacity limits, self‑critique gates, and "audit this lane" / "audit all done lanes" — with every state transition enforced server‑side.
- 📸 Evidence built in. Playwright‑backed screenshots, traces, videos, and logs captured per lane, viewable from anywhere.
- 📱 Phone-ready without public exposure. Scan a QR, enter a one-time code, and drive your agents from your phone over a private Tailscale link. The validated phone path is private web/PWA access; a native iOS shell is present for local builds.
- 🔒 Private by design. Nothing is exposed publicly. The session token lives in an HttpOnly cookie, secrets are referenced never echoed, and the tailnet URL alone leaks nothing until a device pairs.
Quickstart
git clone https://github.com/alex2481kobe/orca.git
cd orca
npm install
npm start
Open http://127.0.0.1:3000/. Because you're on localhost, this machine is your
workstation — Orca trusts it with full control, no pairing or token needed. Keep
that terminal running; Orca lives as long as the npm start process does.
Point it at your code. Create a project and give it a folder on this Mac (an existing directory — a git repo or any folder). That's how Orca "sees your files": agents you launch run inside that folder (each lane in its own git worktree), so they can read and edit that project's code. You pick the folder once per project; Orca only touches folders you add. It starts empty — you bring the projects.
Orca binds to
127.0.0.1(localhost) by default — it's not on any network. To use it from your phone, see Drive it from your phone below. Remote devices see nothing until they pair. For extra hardening you can also require auth on the workstation itself (no implicit local admin):ORCA_API_TOKEN="$(openssl rand -hex 32)" npm start
Drive it from your phone
Keep Orca running on your Mac, front it with Tailscale Serve, and pair your phone once. From then on you can open any project, kick off or stop an agent, watch logs, and review screenshots — from the couch.
Setup is in docs/tailscale-mobile-access.md.
Tailscale Funnel (public exposure) is intentionally not supported.
Drive it from your AI chat (MCP)
Don't want a terminal open per project? Point one chat — Codex CLI / Codex app / Claude Code CLI / Claude Desktop — at Orca over MCP and let that agent orchestrate everything. This is the core Orca loop: one trusted orchestrator agent owns the plan, then Orca fans work out to executor lanes and routes results back through critique and audit.
The primary tested MCP client paths are Codex and Claude. Other MCP-capable desktop apps or CLI clients can use the same stdio server if they can launch a local command with environment variables.
-
On the workstation, generate a scoped orchestrator config (dashboard → Pair → Generate config, or
POST /api/mcp/orchestrator-bootstrap). It mints a short-lived orchestrator tool lease (never your API token) and prints a ready-to-run command. For Claude Code:claude mcp add orca \ -e ORCA_AGENT_TOOLS_BASE_URL=http://127.0.0.1:3000 \ -e ORCA_TOOL_LEASE_TOKEN=<scoped-lease-token> \ -e ORCA_ROLE=orchestrator \ -- node /abs/path/to/src/mcp-server.js(Codex CLI:
codex mcp add orca --env … -- node …. Claude Desktop / Codex app: paste the generated JSON / TOML. Orca isn't on npm — the config uses an absolutenode+mcp-server.jspath, so no source checkout is needed.) -
In the chat, tell it to act as the orchestrator. It will
session__next_action,orchestrator__enrollto claim the session, load a backlog withtask__bulk_add, and — withspawnPolicy:"auto"— Orca fans those tasks out across executor lanes up to capacity. Codex can supervise Claude lanes, Claude can supervise Codex lanes, and either can mix in API-backed or approved custom-CLI lanes. Each lane runs through executor → critique → audit → accepted. Ask it to "show me the lanes" andorchestrator__statusreturns a live tree.orchestrator__resignhands off.
The server enforces the workflow with nextAction envelopes, so the chat can't skip
steps. See docs/desktop-app-control.md.
Prefer the shell? Companion mode (orca-agent) lets any agent drive Orca from
the command line over the same hardened tool surface — zero setup on the local
workstation (orca-agent start "My run" provisions a lease, opens an auto-fan-out
session, and enrolls you). See docs/agent-companion-mode.md.
How it works
Control surfaces — choose one or combine them
──────────────────────────────────────────────────────────
Codex app/CLI · Claude app/CLI ── scoped MCP lease ┐
orca-agent from any shell ── scoped tool lease ├─►
Dashboard / PWA / phone ── browser session ──┘
Your macOS workstation — local-first, never exposed publicly
──────────────────────────────────────────────────────────
Orca server
├─ enforces leases, auth tiers, capacity, and nextAction workflow
├─ captures evidence, logs, screenshots, traces, and audit state
└─► Orchestrator agent (Codex / Claude / orca-agent)
├─► Executor lane (Codex CLI)
├─► Executor lane (Claude CLI)
├─► Executor lane (API provider)
└─► Auditor lane
- Three trust tiers. Public (liveness only) → operator (paired devices: control + read) → admin (the workstation itself: host config, credentials, pairing). A paired phone is always an operator, never an admin — a lost phone can't read secrets or change host settings.
- Tiered data, not a firehose. A lightweight poll + a revision‑signal SSE keep the UI live; full lane detail and the live terminal load only for what you're looking at.
- Provider‑agnostic lanes. Each lane runs through a validated provider profile with its own binary/model/permissions, isolated git worktree, and audit trail.
Security you can trust
Orca treats agent‑spawning, file mutation, and remote access as privileged — and backs it up:
- Session token in an HttpOnly + SameSite + Secure cookie (never in localStorage); the one‑time pairing code is never stored client‑side, and the admin API token is held in memory only — never written to web storage.
- An anti‑DNS‑rebinding Host‑header allowlist gates direct connections, so a
malicious page that resolves its domain to
127.0.0.1can't inherit local admin. - Constant‑time token comparison, SSRF‑hardened URL policy (metadata/private/
obfuscated hosts blocked), approval gates that can't be bypassed, and MCP/exec
env hardening (no
PATH/LD_PRELOAD/NODE_OPTIONSinjection). - Every server‑derived URL is escape‑ and scheme‑checked before render (no
javascript:/ quote‑breakout XSS); secrets are redacted from logs, errors, exports, and support bundles. - A documented route security matrix covers auth, validation, body/rate limits, and audit metadata across ~129 routes.
See SECURITY.md to report issues.
Platforms
- macOS workstation. The validated host path today: run the local Node server, use the web/PWA dashboard, or build the native Tauri shell.
- Phone over Tailscale. The validated remote-operator path: pair once, then use the private web/PWA dashboard from a phone on the same tailnet.
- iOS shell. A native Tauri mobile shell exists for local builds, but the production-ready phone path is still the private web/PWA flow.
- Windows / Linux. The web server path is intended to be portable, but it has not been release-validated on Windows or Linux yet.
- MCP / CLI control.
orca-mcpconnects Codex and Claude desktop/CLI clients;orca-agentlets any shell-capable agent start sessions, add backlog items, and supervise lanes without being an MCP client.
Docs
CONTRIBUTING.md·SECURITY.md·SUPPORT.md·CODE_OF_CONDUCT.md- Tailscale mobile access
- Agent orchestrator / executor skills
- Control Orca from a chat (MCP) · Companion mode (drive Orca from any agent)
- Agent run modes and support matrix
- Live project links
License
AGPL‑3.0‑or‑later — use, study, modify, and share it. Networked or distributed modified versions must keep their source available under the same terms.
Don't rely on prose alone; the authority is the completion ledger and the smoke gates.
npm test— 298 passing unit/integration tests.npm run smoke:acceptance— one‑command end‑to‑end acceptance gate.npm run smoke:ui-inventory/smoke:ui-contract— desktop + 390px phone screenshots of every route with zero horizontal overflow and a shared design contract.npm run smoke:no-hardcoded-colors,smoke:row-menu,smoke:remote-workstation,smoke:pwa-cache,smoke:security, … — focused regression guards.- The ledger tracks 26 areas — 25 implemented & proven, 1 externally blocked (signed native packaging, which needs an Apple Developer ID).