{"slug": "show-hn-hybro-an-open-interoperability-engine-for-ai-agents", "title": "Show HN: Hybro – an open interoperability engine for AI agents", "summary": "Hybro AI released Hybro, an open-source hybrid multi-agent orchestration platform that routes messages between local and remote AI agents using the Agent2Agent (A2A) protocol, distributed via the npm package @hybroai/cli. The platform pairs an async FastAPI backend with a Next.js dashboard for real-time SSE message streaming, multi-agent execution rooms, and an A2A Agent Inspector, and requires Docker Compose v2.24+ (the v1 docker-compose binary is unsupported), Node.js 18+ for the npm CLI, and Python 3.12+ with MongoDB 4.2+ for host-side backend runs. Configuration moved from repository environment files to a single local JSON pair at ~/.hybro/config.json and ~/.hybro/auth.json, with HYBRO_HOME as the sole directory override, and existing installations must run a one-time JSON migration before removing old environment files.", "body_md": "⭐ *Star this repo to support the growing Hybro open-source community!*\n\nHybro AI is an open-source, hybrid multi-agent platform built for seamless agent interoperability. It serves as the core orchestration engine powering the Hybro Agent Network—enabling local and remote AI agents to communicate, collaborate, and execute complex workflows.\n\nHybro AI allows developers and teams to deploy, coordinate, and inspect clusters of autonomous AI agents. Powered by an async FastAPI backend and an interactive Next.js dashboard, Hybro provides real-time agent visualization, execution room management, and protocol-agnostic message routing via the Agent2Agent (A2A) standard.\n\n- **Hybrid Agent Execution** : Seamlessly connect and orchestrate local on-device agents and remote cloud-hosted services.\n- **Native Agent Interoperability** : Built around the open Agent2Agent (A2A) protocol for standardized inter-agent communication.\n- **Multi-Agent Execution Rooms** : Group specialized agents in dedicated execution rooms to solve multi-step tasks collaboratively.\n- **Real-Time Streaming & Inspection** : Live SSE message streaming, multi-agent turn timelines, and an interactive A2A Agent Inspector for testing agent capabilities.\n- **CLI-Managed Configuration** : Configure models and authentication once, then start backend, frontend and Agents without maintaining environment files.\n\n- Docker with Compose v2.24+ (`docker compose` ; the v1`docker-compose` binary is not supported)\n- Node.js 18+ to install the CLI from npm (not needed for release-asset installs)\n- [uv](https://docs.astral.sh/uv/) for host-side`hybro setup` from a checkout\n- Node.js 20.19+ (if running the frontend outside of Docker)\n- Python 3.12+ and MongoDB 4.2+ (if running the backend outside of Docker; Docker Compose uses MongoDB 7.0)\n\nInstall the CLI, configure it, and start the released stack:\n\n```\nnpm install -g @hybroai/cli\nhybro setup          # provider, authentication, models -> ~/.hybro/{config,auth}.json\nhybro start          # pulls the images published for this CLI's version\n```\n\n- **Hybro App** :[http://localhost:3000](http://localhost:3000)\n- **API Server** :[http://localhost:8000](http://localhost:8000)\n- **MCP Server** :[http://127.0.0.1:8001/mcp](http://127.0.0.1:8001/mcp) (Streamable HTTP, same-host clients)\n\nRunning `hybro` with no arguments opens the same settings/services interface in\na terminal. `hybro --version` prints the CLI and stack version.\n\nAlternatively, run the CLI without installing it by unpacking a release asset\n(`hybro-<version>-<platform>.tar.gz` from the GitHub Release) and executing\n`hybro/hybro`.\n\nThe development channel builds images from source instead of pulling them:\n\n```\ngit clone https://github.com/hybroai/hybro.git\ncd hybro\n./scripts/hybro setup\n./scripts/hybro start --build\n```\n\nUse this channel to change Hybro itself or to use settings the published images\ncannot carry (see [Development and released stacks](#development-and-released-stacks)).\n\nExisting installations should perform the one-time JSON migration below before removing old environment files.\n\nBackend, frontend and bundled-agent user settings belong to one local JSON configuration, not repository environment files:\n\n```\n~/.hybro/\n├── config.json   # User settings; edit through the CLI or directly\n└── auth.json     # Credentials; managed through the CLI\n```\n\n`HYBRO_HOME` is the sole directory override and must be an absolute path.\nDefaults, types and validation remain in a thin code loader; JSON only needs\nuser overrides. `backend/common/config/loader.py` replaces the old `settings.py`\nenvironment-loading path. Startup validates syntax, known fields, types, ranges and\nrequired combinations. Missing model setup must direct the user to `hybro setup`;\ninvalid configuration must not silently select a legacy Provider.\n\nCLI edits use the same validation before saving. Manual JSON edits are validated\nat the next startup. Settings are a startup snapshot: restart services after\nchanges with `hybro start --recreate`. Only `api_prefix` needs a rebuild, because\nthe frontend image compiles its server-side API rewrite from it; the browser\nreads every other public setting from the running container.\n\n`.env`, `.env.example` and `frontend/.env.local` are not required by this contract.\nThe CLI supplies only scoped values to containers and frontend builds; transport\nenvironment variables do not become another user configuration source. Secrets\nmust never enter the browser bundle or be forwarded wholesale to Agents.\n\n```\n./scripts/hybro config show\n./scripts/hybro config check\n./scripts/hybro config set backend.log_level '\"DEBUG\"'\n./scripts/hybro config set frontend.max_message_length 12000\n./scripts/hybro start --recreate\n```\n\nUse `config secret <name>` for hidden service-credential input and `setup` for\nProvider/model changes. Startup generates missing internal tokens in `auth.json`\nwithout rotating existing values. Backend overrides live under `backend`, public\nfrontend overrides under `frontend`, and image output size is `image_size`.\n\nWaits for the owner or for a remote Agent:\n\n| Field | Default | Meaning | \n|---|---|---|\n| `backend.approval_deadline_hours` | `null` (no deadline) | Hours before an unanswered supervisor question expires and fails its Run. Must be greater than 0 when set. | \n| `backend.orchestrator_call_wait_ceiling_hours` | `168` (seven days) | Hours an acknowledged remote Agent task is polled with `tasks/get` before the call expires. Must be greater than 0. | \n\n```\n./scripts/hybro config set backend.approval_deadline_hours 48\n./scripts/hybro config set backend.orchestrator_call_wait_ceiling_hours 72.5\n```\n\nA Run waiting for an answer or a remote Agent does not count that time against its profile deadline, so it can wait as long as these limits allow. While it waits it keeps the room's single active-Run slot.\n\nPassthrough Runs (session sends, no orchestrator model turns):\n\n| Field | Default | Meaning | \n|---|---|---|\n| `backend.orchestrator_passthrough_deadline_seconds` | `300` | Active seconds a passthrough Run may take; time spent waiting for the owner or a remote Agent does not count. Must be greater than 0. | \n| `backend.orchestrator_passthrough_max_transport_retries_per_call` | `2` | Transport retries for the single Agent call. Must be greater than 0. | \n\nSessions:\n\n| Field | Default | Meaning | \n|---|---|---|\n| `backend.session_run_start_grace_seconds` | `10` | Seconds after a send without any lifecycle event for the request before the session reports `failed` with`run_not_started` . Must be greater than 0. | \n\nIf you previously ran `hybro setup` and have a `~/.hybro/config.yaml`, convert\nit once (optionally importing known deployment values from the old root `.env`):\n\n```\n./scripts/hybro config migrate --from-env .env\n./scripts/hybro config check\n./scripts/hybro start --recreate\n```\n\nOmit `--from-env` if no deployment values need importing. Migration preserves\nProvider credentials and imports known deployment settings and service secrets;\nit refuses to overwrite an existing `config.json`. Original environment files,\n`.env.example` and `config.yaml` are not deleted.\n\nInstallations that only used the old root `.env` (no YAML setup) must instead\nre-run the interactive setup, then start:\n\n```\n./scripts/hybro setup\n./scripts/hybro start --recreate\n```\n\nAfter either path, normal setup/start uses JSON only, even if the old files\nremain. `migrate` warns when it skips legacy route/model fields it cannot map.\n\nThe already-implemented Agent proxy shares backend's setup-selected gateway. Agents retain SDKs, tools, HITL and A2A execution. Image generation requires an eligible image model; ChatGPT OAuth alone does not enable it.\n\n`./scripts/hybro` is the day-2 lifecycle CLI. Common commands:\n\n```\n./scripts/hybro start                    # up -d, no rebuild (fast daily loop)\n./scripts/hybro start --build            # rebuild images (after code/deps change)\n./scripts/hybro start --recreate         # recreate containers (runtime configuration changes)\n./scripts/hybro start --build --recreate # rebuild and recreate (after code/deps change)\n./scripts/hybro logs backend             # stream one service (or all if no arg)\n./scripts/hybro status                   # docker compose ps --all\n./scripts/hybro stop                     # stop but keep containers\n./scripts/hybro down                     # remove containers + default network\n```\n\nOnly a source checkout can rebuild; a released install changes versions with\n`hybro upgrade`. Configuration never needs a rebuild, except `api_prefix`.\n\nRun `./scripts/hybro --help` for the full subcommand reference. Start through the\nCLI so Compose receives validated scoped projections, not ambient dotenv values.\n\n`hybro start` and the TUI's **Start services** include MCP by default. In the\napp, open **Connect** (`/connect/mcp`) to copy the URL or a setup snippet for your\nassistant. The Overview **Gateway** tile shows whether MCP is reachable. Add the server manually to your client; Hybro does not\nautomatically discover or register MCP clients.\n\n```\n{\n  \"mcpServers\": {\n    \"hybro\": { \"type\": \"http\", \"url\": \"http://127.0.0.1:8001/mcp\" }\n  }\n}\n```\n\nThe **Streamable HTTP** URL is for clients on the machine running Hybro. If you\nopen the app remotely, loopback in your client still refers to that client's\nmachine, not the Hybro host. MCP has no authentication or user isolation and\nsupports only a trusted local mock-auth backend, not Clerk. Do not expose it\npublicly.\n\nUse **Services > MCP connection** in the TUI for status, URL, transport, start,\nstop, logs, and refresh, or run:\n\n```\nhybro mcp status\nhybro mcp start    # requires setup and a running backend; starts only MCP\nhybro mcp logs\nhybro mcp stop\n```\n\nExiting the TUI leaves services running. Stopping MCP is not a persistent opt-out:\nthe next global start includes it again. The app checks MCP status only from the\nOverview **Gateway** tile, when Overview loads; it does not poll in the background,\nand it cannot start/stop services or relay tool calls.\nSee [MCP tools, health, and native startup](https://github.com/hybroai/hybro/blob/main/backend/README.md#local-mcp-access).\n\nThe CLI runs one of two Compose files, both pinned to the `hybro` project name so\ncontainers keep their identity across install locations:\n\n|  | Source checkout | Released install | \n|---|---|---|\n| Stack file | `docker-compose.yml` | `docker-compose.release.yml` | \n| Services come from | local `build:` | published `image:` | \n| Version | the working tree | the CLI's own `VERSION` | \n| Rebuild | `start --build` | not possible; install a newer CLI | \n\n`docker-compose.release.yml` is generated from `docker-compose.yml` by\n`default_agents/render_release.py`, which swaps every `build:` block for an\n`image:` reference. It is checked in and verified by CI, so the two stacks cannot\ndrift. The CLI supplies `HYBRO_STACK_TAG` (its own version) and optionally\n`HYBRO_IMAGE_REGISTRY` when it starts a released stack, which means a released\ninstall always runs the images published for the CLI that started it.\n\nBecause a released install has no sources, `--build` is refused with an explicit\nmessage. Upgrading is how you change versions:\n\n```\nhybro upgrade --check       # report; exits non-zero when a newer release exists\nhybro upgrade               # install it\nhybro start --recreate      # move the containers onto its images\n```\n\nThe container images are pinned to the CLI version, so upgrading the CLI is what\nmoves the stack. `hybro upgrade` replaces an npm install in place; an install\nfrom a release archive prints the download, checksum, and unpack commands\ninstead, because hybro does not overwrite its own directory. A source checkout is\nupdated with `git pull` and `hybro start --build`.\n\nEverything else, including frontend settings, applies at runtime:\n\n```\nhybro config set frontend.max_message_length 12000\nhybro start --recreate      # no rebuild needed\n```\n\nThe one exception is `backend.api_prefix`: the published frontend image compiles\nits server-side API rewrite from the prefix at build time, so changing it needs\nthe checkout channel. The browser reads the rest of the projection from a\nper-request route (`/hybro-runtime-config`) that\n`packaging/frontend/public-config.json` supplies at build time only for that\nrouting.\n\n`release-please` owns version numbers; everything else is produced from them.\n\n1. Merge the release-please PR. It bumps `VERSION` ,`backend/pyproject.toml` ,`frontend/package.json` , and the`packaging/npm/*/package.json` manifests\ntogether, and creates the`v<version>` GitHub Release.\n2. That same workflow then calls the Release workflow as a reusable workflow,\nwhich publishes for that one version: the container images, the four platform\nCLI bundles plus tarballs and checksums on the Release, and the\n`@hybroai/cli*` npm packages.\n3. The final job resolves `docker-compose.release.yml` and confirms every image\nname it references exists, so a stack that points at an unpublished image\nfails the release rather than a user's`hybro start` . It then resolves the\npublished`@hybroai/cli` and confirms every platform package its`optionalDependencies` name is on the registry. npm skips a missing optional\ndependency silently, so nothing else would catch it: the launcher installs,\nand the wrapper only fails at run time with an \"is not installed\" message.\n\nThe Release workflow is called rather than triggered by `release: published`\nbecause release-please acts with `GITHUB_TOKEN`, and GitHub does not start\nworkflows for events that token triggers — a release event would never arrive.\n`workflow_dispatch` remains for re-publishing after a failure; give it the\nversion so a retry cannot silently publish whatever `VERSION` happens to say.\nThe same rule explains why release-please PRs get no automatic CI: GitHub does\nstart those runs, but holds them until someone with write access approves them.\n\nRequirements for the workflow: an `NPM_TOKEN` repository secret with publish\nrights for the `@hybroai` scope, and the scope must already exist on npm.\nPublishing the images also needs the `ghcr.io/hybroai` packages to be public;\nGitHub creates them private, and a private image makes `hybro start` fail with\nan authorization error.\n\n`backend/uv.lock` records the project's own version and release-please does not\nupdate it, so a release leaves it one version behind. `uv sync --frozen`\ntolerates that, but `uv lock --check` does not.\n\nBuild the CLI locally with `packaging/cli/build.sh`, then stage it for npm with\n`packaging/npm/build.sh <darwin-arm64|darwin-x64|linux-arm64|linux-x64>`. Releases\nship a PyInstaller **onefile** executable: a single binary with no symbolic\nlinks, because npm's packer drops links and a macOS onedir bundle depends on\nfour of them. The bundle extracts to a new temporary directory per run, which is\nwhy both Compose files pin `name: hybro`.\n\nThis repository is the source of truth for the product. Its frontend and backend\nare the in-repository `frontend/` and `backend/` directories used by Docker\nCompose and CI.\n\nThe repository is split into these primary components:\n\n- `backend/` : A FastAPI orchestration engine using MongoDB for persistence and optional Redis services for cross-process coordination.\n- `frontend/` : A Next.js 16 (Turbopack) application for chat, local agent discovery, agent management, and inspection.\n- `default_agents/` : A collection of ready-to-use A2A agents, each running as its own container, plus a one-shot`registrar` that registers them with the backend on startup.\n- `MCP/` : A standalone adapter exposing two backend agent-network tools over Streamable HTTP, built with its own Dockerfile and published as the version-pinned`hybro-mcp` image.\n\nUse `hybro setup` for OpenAI API Key or ChatGPT OAuth, DeepSeek API Key, or\nAnthropic API Key.\nAgents receive a scoped `HYBRO_AGENT_CONFIG` projection containing the backend\nproxy URL, a separate inference token and image size. They pass these values\nexplicitly to their SDKs. The token cannot authenticate as a user or registrar;\nit is required even under mock auth. Agents never receive Provider credentials\nor the setup directory.\nSee [gateway architecture](https://github.com/hybroai/hybro/blob/main/backend/docs/System-Architecture.md#llm_gateway) for\nthe supported proxy subset and limits.\n\nWe welcome contributions from the community! Whether you are fixing a bug, adding a feature, or improving documentation, please feel free to open a pull request.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature` )\n3. Commit your changes (`git commit -m 'feat: add amazing feature'` )\n4. Push to the branch (`git push origin feature/amazing-feature` )\n5. Open a Pull Request\n\nApache License 2.0", "url": "https://wpnews.pro/news/show-hn-hybro-an-open-interoperability-engine-for-ai-agents", "canonical_source": "https://github.com/hybroai/hybro", "published_at": "2026-10-18 23:41:45+00:00", "updated_at": "2026-10-18 23:48:29.282296+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Hybro AI", "Hybro", "Agent2Agent", "FastAPI", "Next.js", "MongoDB", "@hybroai/cli", "Docker Compose"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-hybro-an-open-interoperability-engine-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-hybro-an-open-interoperability-engine-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-hybro-an-open-interoperability-engine-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-hybro-an-open-interoperability-engine-for-ai-agents.jsonld"}}