Hybro AI emerges as an open-source, hybrid multi-agent platform designed for seamless interoperability between local and remote AI agents. The project positions itself as the core orchestration engine for the Hybro Agent Network, enabling developers and teams to deploy, coordinate, and inspect clusters of autonomous agents working together on complex workflows.

Architecture and core components

The repository organizes into four primary directories. The backend/ directory houses a FastAPI orchestration engine that persists state in MongoDB and optionally uses Redis for cross-process coordination. The frontend/ directory presents a Next.js 16 application built with Turbopack, offering chat interfaces, local agent discovery, management tools, and inspection capabilities. The default_agents/ directory provides ready-to-use A2A agents each running in their own container along with a one-shot registrar that registers agents with the backend on startup. The MCP/ directory exposes a standalone adapter that makes two backend agent-network tools available over Streamable HTTP.

Agent interoperability and execution model

Hybro implements the open Agent2Agent (A2A) protocol as the foundation for standardized inter-agent communication. This protocol-agnostic routing allows local on-device agents and remote cloud-hosted services to connect and orchestrate seamlessly. Developers can group specialized agents into dedicated execution rooms to solve multi-step tasks collaboratively. The platform supports real-time SSE message streaming and multi-agent turn timelines, with an interactive A2A Agent Inspector for testing agent capabilities.

Execution model distinguishes between two run types. Standard runs may wait for owner approval or remote agent responses, with configurable deadlines measured in hours. Passthrough runs send sessions without orchestrator model turns, subject to their own deadline and retry configuration. Session management includes a grace period of 10 seconds after a send without any lifecycle event before the session reports failed with run_not_started.

Configuration and runtime setup

Configuration lives in a single local JSON directory at ~/.hybro/, containing config.json for user settings and auth.json for credentials. A thin code loader in backend/common/config/loader.py replaces the former settings.py environment-loading path, validating syntax, known fields, types, ranges, and required combinations at startup. The CLI manages configuration through subcommands like config show, config check, and config set, with all edits validated before saving and manual JSON edits validated at the next service restart.

Runtime configuration changes generally require only a service restart with hybro start --recreate, except for the backend.api_prefix field, which necessitates a source checkout rebuild since the published frontend image compiles its server-side API rewrite from the prefix at build time. Environment files such as .env, .env.example, and frontend/.env.local are not part of the configuration contract; the CLI supplies only scoped values to containers and frontend builds.

New installations begin with npm install -g @hybroai/cli followed by hybro setup to configure providers, authentication, and model selections. The CLI then pulls published images matching its version with hybro start. Existing installations migrating from older config.yaml or .env files can use hybro config migrate --from-env .env to preserve provider credentials and import known deployment settings, refusing to overwrite an existing config.json.

Container orchestration and upgrade workflow

The CLI manages two distinct Compose stacks. Source checkouts use docker-compose.yml with local builds, while released installs use docker-compose.release.yml with published images. The release workflow generates the release stack from the source stack via default_agents/render_release.py, which replaces every build: block with an image: reference. CI verifies the two stacks cannot drift. Container images pin to the CLI version, meaning version changes require hybro upgrade rather than direct compose modifications.

The upgrade pathway involves hybro upgrade --check to report available updates, hybro upgrade to install the new CLI version, and hybro start --recreate to move containers onto the new images. Source checkouts update via git pull followed by hybro start --build. Released installs cannot rebuild; they must upgrade the CLI to change versions.

MCP integration and agent proxy

Multi-Component Protocol (MCP) support ships by default with hybro start and the TUI's Start services. Within the app, users can open Connect (/connect/mcp) to copy the URL or a setup snippet for their assistant. The Overview Gateway tile displays whether MCP remains reachable. MCP configuration appears as a JSON object mapping server names to HTTP type and URL, with the default entry pointing to http://127.0.0.1:8001/mcp.

MCP operates as a streamable HTTP adapter without authentication or user isolation, supporting only a trusted local mock-auth backend. The platform does not automatically discover or register MCP clients; users must add servers manually. Exposing MCP publicly is discouraged given its trust-based design. Day-2 CLI operations include hybro mcp status, hybro mcp start, hybro mcp logs, and hybro mcp stop.

Developer practicalities

Developers running the backend outside Docker need Python 3.12+ and MongoDB 4.2+, while the full Docker Compose stack uses MongoDB 7.0. Node.js 18+ installs the CLI from npm, and running the frontend outside Docker requires Node.js 20.19+. The uv tool handles host-side setup from checkouts. Python dependencies lock to project version via backend/uv.lock, which release-please does not update, leaving releases one version behind—uv sync --frozen tolerates this, but uv lock --check flags it.

The platform's release pipeline uses release-please to own version numbers, bumping VERSION across backend/pyproject.toml, frontend/package.json, and packaging/npm/*/package.json manifests before creating a versioned GitHub Release. The subsequent Release workflow publishes container images, four platform CLI bundles, tarballs and checksums, and @hybroai/cli npm packages. Publication requires NPM_TOKEN with scope publish rights and public ghcr.io/hybroai packages; private container images cause hybro start to fail with authorization errors.

Local builds use PyInstaller to produce a onefile executable, chosen because npm's packer drops symbolic links required by macOS onedir bundles. Both Compose files pin container name: hybro since the bundle extracts to a new temporary directory per run. Development channel users building from source execute ./scripts/hybro setup and ./scripts/hybro start --build to incorporate code and dependency changes.