Skip to content
Coro Docs

Hybrid mode (team cloud plane)

Hybrid mode keeps the heavy LLM workloads on developers’ laptops (or shared agent hosts) while PostgreSQL-backed cloud services unify identity, webhook ingress, queued events, optional dashboard hosting, and cross-runner routing (/concepts/overview/, /concepts/architecture/).

What the dashboard covers vs CLI

Most day-to-day settings still live in the local dashboard Settings UI on each runner—LLM auth, SCM, trackers, guardrails, MCP, and paths work the same as solo mode (/getting-started/providers/).

Hybrid pairing is the main exception: connecting a runner to the cloud control plane writes the cloud block (url + token) via CLI today—there is no dedicated Settings section for cloud login.

ConcernDashboardCLI / JSON
LLM, SCM, tracker, guardrails, MCP, pathsSettingsOptional config.json edit
Cloud control plane pairing—coro login
Job enqueue, status, logsRuns, New Runcoro job, coro status, coro logs

Prerequisites

Self-hosted reference stack: @coro-ai/runner src/cloud/ compose file (packages/runner/docker-compose.cloud.yml). Production equivalents should mirror the same processes:

  • Postgres (Drizzle schema)
  • HTTPS edge terminating webhook POSTs (/webhook/:teamId/:pluginId)
  • WebSocket gateway for runner sockets + fan-out envelopes (event:webhook, event:pluginWebhook)

Bootstrap on a laptop

  1. Ensure coro CLI reachable — see /contributing/local-setup/.
  2. Configure providers in Settings (LLM, source control, optional tracker) before pairing.
  3. Run coro login — gathers email/password (or scripted flags), obtains access + refresh JWT, resolves team, generates runner token, writes cloud block into ~/.coro/config.json with URL + bearer token (packages/runner/cli/commands/login.ts).
  4. Start coro start — runner connects outbound WebSocket (hybrid-dispatcher.ts) and swaps SQLite persistence for batched RPCs when cloud transport attaches.

JWT subject becomes tenantId team-<teamId>, affecting overlay routing & analytics—document naming for support.

Operational characteristics

ConcernSoloHybrid
State~/.coro/state.dbPostgres row per job/event
WebhooksTunnel/ngrok/manual pollStable HTTPS ingress with HMAC (/guides/webhooks/)
Token fan-outn/aCloud ensures job belongs to owning runner

Overlay distribution

Set Settings → Advanced → Paths → Intelligence git remote (or explicit tenant.overlay) on each runner so every team member resolves the same tenant layer. Upstream roadmap calls for cloud-fed overlay descriptors; until then teams standardise overlays via Git remotes (/guides/tenant-overlay/).

Failure modes & recovery

  • Stale runner token — rerun coro login; tokens may be revoked from cloud admin UI once exposed.
  • Split brain — two runners attaching same hostname; enforce unique runner names per workstation.
  • Webhook misroute — mis-typed /webhook/:teamId/:pluginId URL yields 404 spam and stuck jobs awaiting merges—verify plugin id matches SCM configuration in Settings → Extensions → Plugins.