⭐ Star this repo to support the growing Hybro open-source community!
Hybro 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.
Hybro 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.
-
Hybrid Agent Execution : Seamlessly connect and orchestrate local on-device agents and remote cloud-hosted services.
-
Native Agent Interoperability : Built around the open Agent2Agent (A2A) protocol for standardized inter-agent communication.
-
Multi-Agent Execution Rooms : Group specialized agents in dedicated execution rooms to solve multi-step tasks collaboratively.
-
Real-Time Streaming & Inspection : Live SSE message streaming, multi-agent turn timelines, and an interactive A2A Agent Inspector for testing agent capabilities.
-
CLI-Managed Configuration : Configure models and authentication once, then start backend, frontend and Agents without maintaining environment files.
-
Docker with Compose v2.24+ (
docker compose; the v1docker-composebinary is not supported) -
Node.js 18+ to install the CLI from npm (not needed for release-asset installs)
-
uv for host-side
hybro setupfrom a checkout -
Node.js 20.19+ (if running the frontend outside of Docker)
-
Python 3.12+ and MongoDB 4.2+ (if running the backend outside of Docker; Docker Compose uses MongoDB 7.0)
Install the CLI, configure it, and start the released stack:
npm install -g @hybroai/cli
hybro setup # provider, authentication, models -> ~/.hybro/{config,auth}.json
hybro start # pulls the images published for this CLI's version
- Hybro App :http://localhost:3000
- API Server :http://localhost:8000
- MCP Server :http://127.0.0.1:8001/mcp (Streamable HTTP, same-host clients)
Running hybro with no arguments opens the same settings/services interface in
a terminal. hybro --version prints the CLI and stack version.
Alternatively, run the CLI without installing it by unpacking a release asset
(hybro-<version>-<platform>.tar.gz from the GitHub Release) and executing
hybro/hybro.
The development channel builds images from source instead of pulling them:
git clone https://github.com/hybroai/hybro.git
cd hybro
./scripts/hybro setup
./scripts/hybro start --build
Use this channel to change Hybro itself or to use settings the published images cannot carry (see Development and released stacks).
Existing installations should perform the one-time JSON migration below before removing old environment files.
Backend, frontend and bundled-agent user settings belong to one local JSON configuration, not repository environment files:
~/.hybro/
├── config.json # User settings; edit through the CLI or directly
└── auth.json # Credentials; managed through the CLI
HYBRO_HOME is the sole directory override and must be an absolute path.
Defaults, types and validation remain in a thin code ; JSON only needs
user overrides. backend/common/config/.py replaces the old settings.py
environment- path. Startup validates syntax, known fields, types, ranges and
required combinations. Missing model setup must direct the user to hybro setup;
invalid configuration must not silently select a legacy Provider.
CLI edits use the same validation before saving. Manual JSON edits are validated
at the next startup. Settings are a startup snapshot: restart services after
changes with hybro start --recreate. Only api_prefix needs a rebuild, because
the frontend image compiles its server-side API rewrite from it; the browser
reads every other public setting from the running container.
.env, .env.example and frontend/.env.local are not required by this contract.
The CLI supplies only scoped values to containers and frontend builds; transport
environment variables do not become another user configuration source. Secrets
must never enter the browser bundle or be forwarded wholesale to Agents.
./scripts/hybro config show
./scripts/hybro config check
./scripts/hybro config set backend.log_level '"DEBUG"'
./scripts/hybro config set frontend.max_message_length 12000
./scripts/hybro start --recreate
Use config secret <name> for hidden service-credential input and setup for
Provider/model changes. Startup generates missing internal tokens in auth.json
without rotating existing values. Backend overrides live under backend, public
frontend overrides under frontend, and image output size is image_size.
Waits for the owner or for a remote Agent:
| Field | Default | Meaning |
|---|---|---|
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. |
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. |
./scripts/hybro config set backend.approval_deadline_hours 48
./scripts/hybro config set backend.orchestrator_call_wait_ceiling_hours 72.5
A 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.
Passthrough Runs (session sends, no orchestrator model turns):
| Field | Default | Meaning |
|---|---|---|
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. |
backend.orchestrator_passthrough_max_transport_retries_per_call |
2 |
Transport retries for the single Agent call. Must be greater than 0. |
Sessions:
| Field | Default | Meaning |
|---|---|---|
backend.session_run_start_grace_seconds |
10 |
Seconds after a send without any lifecycle event for the request before the session reports failed withrun_not_started . Must be greater than 0. |
If you previously ran hybro setup and have a ~/.hybro/config.yaml, convert
it once (optionally importing known deployment values from the old root .env):
./scripts/hybro config migrate --from-env .env
./scripts/hybro config check
./scripts/hybro start --recreate
Omit --from-env if no deployment values need importing. Migration preserves
Provider credentials and imports known deployment settings and service secrets;
it refuses to overwrite an existing config.json. Original environment files,
.env.example and config.yaml are not deleted.
Installations that only used the old root .env (no YAML setup) must instead
re-run the interactive setup, then start:
./scripts/hybro setup
./scripts/hybro start --recreate
After either path, normal setup/start uses JSON only, even if the old files
remain. migrate warns when it skips legacy route/model fields it cannot map.
The 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.
./scripts/hybro is the day-2 lifecycle CLI. Common commands:
./scripts/hybro start # up -d, no rebuild (fast daily loop)
./scripts/hybro start --build # rebuild images (after code/deps change)
./scripts/hybro start --recreate # recreate containers (runtime configuration changes)
./scripts/hybro start --build --recreate # rebuild and recreate (after code/deps change)
./scripts/hybro logs backend # stream one service (or all if no arg)
./scripts/hybro status # docker compose ps --all
./scripts/hybro stop # stop but keep containers
./scripts/hybro down # remove containers + default network
Only a source checkout can rebuild; a released install changes versions with
hybro upgrade. Configuration never needs a rebuild, except api_prefix.
Run ./scripts/hybro --help for the full subcommand reference. Start through the
CLI so Compose receives validated scoped projections, not ambient dotenv values.
hybro start and the TUI's Start services include MCP by default. In the
app, open Connect (/connect/mcp) to copy the URL or a setup snippet for your
assistant. The Overview Gateway tile shows whether MCP is reachable. Add the server manually to your client; Hybro does not
automatically discover or register MCP clients.
{
"mcpServers": {
"hybro": { "type": "http", "url": "http://127.0.0.1:8001/mcp" }
}
}
The Streamable HTTP URL is for clients on the machine running Hybro. If you open the app remotely, loopback in your client still refers to that client's machine, not the Hybro host. MCP has no authentication or user isolation and supports only a trusted local mock-auth backend, not Clerk. Do not expose it publicly.
Use Services > MCP connection in the TUI for status, URL, transport, start, stop, logs, and refresh, or run:
hybro mcp status
hybro mcp start # requires setup and a running backend; starts only MCP
hybro mcp logs
hybro mcp stop
Exiting the TUI leaves services running. Stopping MCP is not a persistent opt-out: the next global start includes it again. The app checks MCP status only from the Overview Gateway tile, when Overview loads; it does not poll in the background, and it cannot start/stop services or relay tool calls. See MCP tools, health, and native startup.
The CLI runs one of two Compose files, both pinned to the hybro project name so
containers keep their identity across install locations:
| Source checkout | Released install | |
|---|---|---|
| Stack file | docker-compose.yml |
docker-compose.release.yml |
| Services come from | local build: |
published image: |
| Version | the working tree | the CLI's own VERSION |
| Rebuild | start --build |
not possible; install a newer CLI |
docker-compose.release.yml is generated from docker-compose.yml by
default_agents/render_release.py, which swaps every build: block for an
image: reference. It is checked in and verified by CI, so the two stacks cannot
drift. The CLI supplies HYBRO_STACK_TAG (its own version) and optionally
HYBRO_IMAGE_REGISTRY when it starts a released stack, which means a released
install always runs the images published for the CLI that started it.
Because a released install has no sources, --build is refused with an explicit
message. Upgrading is how you change versions:
hybro upgrade --check # report; exits non-zero when a newer release exists
hybro upgrade # install it
hybro start --recreate # move the containers onto its images
The container images are pinned to the CLI version, so upgrading the CLI is what
moves the stack. hybro upgrade replaces an npm install in place; an install
from a release archive prints the download, checksum, and unpack commands
instead, because hybro does not overwrite its own directory. A source checkout is
updated with git pull and hybro start --build.
Everything else, including frontend settings, applies at runtime:
hybro config set frontend.max_message_length 12000
hybro start --recreate # no rebuild needed
The one exception is backend.api_prefix: the published frontend image compiles
its server-side API rewrite from the prefix at build time, so changing it needs
the checkout channel. The browser reads the rest of the projection from a
per-request route (/hybro-runtime-config) that
packaging/frontend/public-config.json supplies at build time only for that
routing.
release-please owns version numbers; everything else is produced from them.
- Merge the release-please PR. It bumps
VERSION,backend/pyproject.toml,frontend/package.json, and thepackaging/npm/*/package.jsonmanifests together, and creates thev<version>GitHub Release. - That same workflow then calls the Release workflow as a reusable workflow,
which publishes for that one version: the container images, the four platform
CLI bundles plus tarballs and checksums on the Release, and the
@hybroai/cli*npm packages. - The final job resolves
docker-compose.release.ymland confirms every image name it references exists, so a stack that points at an unpublished image fails the release rather than a user'shybro start. It then resolves the published@hybroai/cliand confirms every platform package itsoptionalDependenciesname is on the registry. npm skips a missing optional dependency silently, so nothing else would catch it: the launcher installs, and the wrapper only fails at run time with an "is not installed" message.
The Release workflow is called rather than triggered by release: published
because release-please acts with GITHUB_TOKEN, and GitHub does not start
workflows for events that token triggers — a release event would never arrive.
workflow_dispatch remains for re-publishing after a failure; give it the
version so a retry cannot silently publish whatever VERSION happens to say.
The same rule explains why release-please PRs get no automatic CI: GitHub does
start those runs, but holds them until someone with write access approves them.
Requirements for the workflow: an NPM_TOKEN repository secret with publish
rights for the @hybroai scope, and the scope must already exist on npm.
Publishing the images also needs the ghcr.io/hybroai packages to be public;
GitHub creates them private, and a private image makes hybro start fail with
an authorization error.
backend/uv.lock records the project's own version and release-please does not
update it, so a release leaves it one version behind. uv sync --frozen
tolerates that, but uv lock --check does not.
Build the CLI locally with packaging/cli/build.sh, then stage it for npm with
packaging/npm/build.sh <darwin-arm64|darwin-x64|linux-arm64|linux-x64>. Releases
ship a PyInstaller onefile executable: a single binary with no symbolic
links, because npm's packer drops links and a macOS onedir bundle depends on
four of them. The bundle extracts to a new temporary directory per run, which is
why both Compose files pin name: hybro.
This repository is the source of truth for the product. Its frontend and backend
are the in-repository frontend/ and backend/ directories used by Docker
Compose and CI.
The repository is split into these primary components:
backend/: A FastAPI orchestration engine using MongoDB for persistence and optional Redis services for cross-process coordination.frontend/: A Next.js 16 (Turbopack) application for chat, local agent discovery, agent management, and inspection.default_agents/: A collection of ready-to-use A2A agents, each running as its own container, plus a one-shotregistrarthat registers them with the backend on startup.MCP/: A standalone adapter exposing two backend agent-network tools over Streamable HTTP, built with its own Dockerfile and published as the version-pinnedhybro-mcpimage.
Use hybro setup for OpenAI API Key or ChatGPT OAuth, DeepSeek API Key, or
Anthropic API Key.
Agents receive a scoped HYBRO_AGENT_CONFIG projection containing the backend
proxy URL, a separate inference token and image size. They pass these values
explicitly to their SDKs. The token cannot authenticate as a user or registrar;
it is required even under mock auth. Agents never receive Provider credentials
or the setup directory.
See gateway architecture for
the supported proxy subset and limits.
We 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.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Apache License 2.0