Conduit

Cross-agent task delegation over MQTT. Honest by design.

A config-driven, persistent, multi-peer MQTT delegation bridge with a Hermes skill as the primary interface. Install, configure, delegate.

Quick start

pip install conduit
conduit config init
conduit doctor
conduit send --to dusk --method research --params '{"query":"Amazon PPC 2026"}'

What's new in V2

• Config file (~/.conduit/config.yaml) — zero-config default, additive overrides
• Persistent listen with auto-reconnect — replaces separate listener scripts
• Hermis skill — teaches agents when/how to use Conduit
• Multi-peer — any agent id, not just Vader↔Dusk
• Retry (opt-in) with exponential backoff, single-invocation scope
• Idempotency via request_id dedup in outbox
• conduit doctor — validates config and checks broker reachability
• Honest transport — CONNACK rc=0, PUBACK round-trip, no phantom successes

CLI commands

Command	Description
conduit send --to <peer> --method <m> --params '<json>'	Send a task request
conduit poll --window <seconds>	Poll for responses
conduit listen [--wildcard]	Persistent listener with auto-reconnect
conduit status	Show broker, agent id, pending count
conduit config init	Create default config file
conduit config show	Print current config
conduit config get <key>	Get a config value (dot notation)
conduit config set <key> <value>	Set a config value
conduit doctor	Validate config and check broker

Configuration

Default config at ~/.conduit/config.yaml:

agent:
  id: auto           # hostname fallback, then None
broker:
  host: broker.emqx.io
  port: 1883
peers:
  dusk:
    convention: hermes
behavior:
  default_convention: hermes
  retry:
    max_attempts: 0   # disabled by default
  connection:
    clean_session_listen: false
    clean_session_send: true

Contract

Direction	Topic	Envelope
A → B	hermes/agents/<from>/<to>/msg	{request_id, from, to, method, params, ts}
B → A	hermes/agents/<from>/<to>/result	{from, to, type, request_id, result, ts}
Inbox	hermes/agents/<agent>/+/result	—

License

MIT. See LICENSE.

Tech Stack

Layer	Technology
Language	Python 3
MQTT Client	paho-mqtt
Config	YAML (PyYAML)
CLI	argparse
Testing	pytest
Package	pip

📊 Codegraph

See codegraphs/conduit.md for the full dependency graph.