Usage

Configuration

Hybro Hub reads its configuration from ~/.hybro/config.yaml. Create the config directory and file:

mkdir -p ~/.hybro

A minimal ~/.hybro/config.yaml only needs your API key:

cloud:
  api_key: ${HYBRO_API_KEY}   # or paste directly: "hybro_your_key_here"

A fully-annotated example with all sections:

# Cloud connection
cloud:
  api_key: ${HYBRO_API_KEY}          # or ${HYBRO_API_KEY:-} to allow unset
  gateway_url: "https://api.hybro.ai"
 
# Agent discovery
agents:
  auto_discover: true                  # probe localhost ports for A2A agents
  auto_discover_exclude_ports:         # skip non-agent ports (built-in defaults shown)
    - 22    # SSH
    - 53    # DNS
    - 80    # HTTP
    - 443   # HTTPS
    - 3306  # MySQL
    - 5432  # PostgreSQL
    - 6379  # Redis
    - 27017 # MongoDB
  # auto_discover_scan_range: [10000, 11000]  # restrict scan to a port range
 
  # Manually-configured agents (always registered, even if auto_discover is off)
  local:
    - name: "My Custom Agent"
      url: "http://localhost:9001"
    - name: "Remote Agent"
      url: "http://192.168.1.50:8080"  # LAN agents work too
 
# Privacy (classification is logging-only; messages are not blocked or rerouted)
privacy:
  sensitive_keywords: ["medical", "financial", "confidential"]
  sensitive_patterns: ["PROJ-\\d{4}"]
 
# Offline resilience — events that fail delivery are queued to disk and retried
publish_queue:
  enabled: true
  max_size_mb: 50
  ttl_hours: 24
  drain_interval: 30        # seconds between retry cycles
  drain_batch_size: 20
  max_retries_critical: 20  # agent_response, agent_error, processing_status
  max_retries_normal: 5     # task_submitted, artifact_update, task_status
 
# Heartbeat interval (seconds)
heartbeat_interval: 30

Environment Variable Syntax

The config file supports environment variable references expanded before YAML parsing (matching the OTel Collector convention):

Set the API key in your shell profile:

export HYBRO_API_KEY="hybro_..."

Or pass it once on the CLI (saved to the config file):

hybro-hub start --api-key hybro_...

If the config file already contains an env var reference (e.g. api_key: ${HYBRO_API_KEY}), the CLI will not overwrite it — your env var wiring is preserved.

Environment Variable Overrides

The following shell variables are also checked at startup and override whatever is in the config file:

Running the Hub

Start the hub daemon:

hybro-hub start --api-key hybro_...

The API key is saved to ~/.hybro/config.yaml after first use — subsequent starts don’t need it.

The hub will:

1. Register with the Hybro relay service
2. Discover local A2A agents
3. Sync agent list to the cloud
4. Begin listening for incoming messages

The hub starts in the background by default. Logs are written to ~/.hybro/hub.log. To keep it attached to the terminal instead, use --foreground:

hybro-hub start --foreground

With debug logging:

hybro-hub -v start

CLI Commands

hybro-hub start

Start the hub daemon in the background:

hybro-hub start
hybro-hub start --api-key hybro_...   # provide key on first run
hybro-hub start --foreground          # stay attached to the terminal

hybro-hub stop

Stop the running hub daemon:

hybro-hub stop

hybro-hub status

Check if the hub is running and how many agents are synced to the cloud:

hybro-hub status

hybro-hub agents

List all discovered local agents and their health status:

hybro-hub agents

hybro-hub agent start

Launch a local A2A agent from a bundled adapter. Requires a2a-adapter package (pip install "hybro-hub[ollama]").

Ollama — local LLM (requires Ollama ):

hybro-hub agent start ollama
hybro-hub agent start ollama --model mistral:7b --port 10020 --system-prompt "You are a helpful assistant"

OpenClaw — AI coding agent (requires OpenClaw ):

hybro-hub agent start openclaw
hybro-hub agent start openclaw --thinking medium --agent-id main

n8n — workflow automation (requires a running n8n  instance):

hybro-hub agent start n8n --webhook-url http://localhost:5678/webhook/my-agent

Common options:

Adapter-specific options:

Using a config file

For options not available as CLI flags (e.g. Ollama temperature, OpenClaw working_directory), use --config with a YAML file:

hybro-hub agent start --config hybro-agent.yaml

CLI flags (--port, --name, --timeout) override values in the config file when explicitly provided.

If hybro-agent.yaml or .hybro-agent.yaml exists in the current directory, hybro-hub agent start (with no arguments) auto-discovers and uses it.

Ollama config file:

adapter: ollama
name: "My Ollama Agent"           # display name in hybro.ai
port: 10010                        # local A2A server port
 
model: llama3.2                    # any model pulled via `ollama pull`
base_url: http://localhost:11434   # Ollama server URL (default shown)
system_prompt: "You are a helpful assistant"
temperature: 0.7                   # omit to use Ollama's default
timeout: 120                       # request timeout in seconds
keep_alive: "5m"                   # how long Ollama keeps the model loaded

OpenClaw config file:

adapter: openclaw
name: "My OpenClaw Agent"          # display name in hybro.ai
port: 10010                         # local A2A server port
 
thinking: low                       # off / minimal / low / medium / high / xhigh
agent_id: main                      # OpenClaw agent ID (optional)
openclaw_path: openclaw             # path to binary if not on PATH
timeout: 600                        # command timeout in seconds
working_directory: /path/to/repo    # working directory for openclaw (optional)
env_vars:                           # environment variables for the subprocess (optional)
  MY_VAR: "value"

n8n config file:

adapter: n8n
name: "My n8n Agent"
port: 10010
webhook_url: http://localhost:5678/webhook/my-agent
message_field: event                # field in the webhook payload that carries the user message
timeout: 30

Agent Discovery

Auto-Discovery

When auto_discover: true (the default), the hub:

1. Enumerates all listening TCP ports on localhost using OS-native strategies
2. Skips well-known service ports (22, 53, 80, 443, 3306, 5432, 6379, 27017) and any ports in auto_discover_exclude_ports
3. Probes each port for /.well-known/agent.json (also checks /.well-known/agent-card.json)
4. Registers any valid A2A agents found

Auto-discovery runs at startup and re-scans periodically (every 120 seconds).

To restrict scanning to a specific port range (useful on machines with many open ports):

agents:
  auto_discover_scan_range: [10000, 11000]

Manual Configuration

You can also specify agents explicitly in config.yaml:

agents:
  local:
    - name: "My Research Agent"
      url: "http://localhost:9001"
    - name: "Team Agent"
      url: "http://192.168.1.50:8080"  # LAN agents work too

Manually configured agents are always registered, even if auto_discover is disabled.

Excluding Ports

To skip additional ports during auto-discovery:

agents:
  auto_discover_exclude_ports:
    - 8080  # your web server
    - 3000  # your frontend dev server

Health Monitoring

The hub performs health checks every 60 seconds:

• Fetches each agent’s agent card (/.well-known/agent.json or /.well-known/agent-card.json)
• Agents that fail 3 consecutive health checks are removed
• Recovered agents are automatically re-registered

Check current agent health:

hybro-hub agents

Privacy Classification

The hub can detect sensitive data in outbound messages. Classification is logging-only — messages are not blocked or rerouted. Active blocking and anonymization are planned for a future release.

Every message in hybro.ai shows where it was processed:

• Local — processed on your machine, data did not leave
• Cloud — processed by a cloud agent via hybro.ai

What it detects

Built-in PII patterns: email addresses, phone numbers, SSNs, credit card numbers, API keys.

Custom keywords and patterns (configured in config.yaml):

privacy:
  sensitive_keywords:
    - "medical"
    - "financial"
  sensitive_patterns:
    - "PROJ-\\d{4}"
    - "INTERNAL-\\w+"

When sensitive content is detected, the hub logs a warning with the classification. The message is still dispatched normally.

Built-in Adapters

Ollama

Run a local Ollama LLM as an A2A agent:

# Make sure Ollama is running (ollama serve)
hybro-hub agent start ollama --model llama3.2

This starts an A2A server on port 10010 (configurable with --port). The hub will auto-discover it and make it available on the Hybro platform.

For full configuration (temperature, custom base URL, keep-alive), use a config file — see Using a config file in the CLI Commands section.

OpenClaw

Run an AI coding agent:

hybro-hub agent start openclaw
hybro-hub agent start openclaw --thinking medium --agent-id main

To set a working directory or pass environment variables to the subprocess, use a config file — see Using a config file in the CLI Commands section.

n8n

Connect an n8n workflow as an A2A agent:

hybro-hub agent start n8n --webhook-url http://localhost:5678/webhook/my-agent

All three adapters come from the same a2a-adapter package: pip install "hybro-hub[ollama]"

Bring Your Own Agent

Any agent that speaks the A2A protocol  works with Hybro Hub. Use the a2a-python SDK  (pip install a2a-sdk) or Google ADK  (pip install google-adk) to build a compatible agent:

from a2a.server.apps import A2AStarletteApplication
from a2a.server.request_handlers import DefaultRequestHandler
 
app = A2AStarletteApplication(
    agent_card=my_card,
    http_handler=DefaultRequestHandler(agent_executor=my_executor),
)

Start it on any port — the hub discovers it automatically and syncs it to hybro.ai.

Lifecycle

The hub daemon runs the following background tasks concurrently:

The daemon handles SIGINT and SIGTERM for graceful shutdown.