Hive logo

Hive

Agent coordination, distributed work.

What it is

Hive is fleet-wide agent coordination plus a triage queue. Orchestrator runtimes submit work orders, worker runtimes claim and run them, and a doctor worker triages whatever fails.

There is one bus and many workers, and no central scheduler. The one dispatch mechanism is the /v1/jobs/next dequeue: a worker asks the bus for its next job.

The three parts

The architecture document gives the file and function behind each of these claims.

How a job moves

A job is created as queued, claimed by a worker, marked running, then finished as done or failed. needs-review is a quarantine stop for completions that lack evidence. cancelled and dead-letter retire work. offered and released are transient states the API still validates.

The complete transition table, checked by machine (STATUS_TRANSITIONS in hive/bus/domain/jobs.py):

FromAllowed next statuses
queuedqueued, offered, claimed, cancelled
offeredqueued, claimed, cancelled
claimedqueued, claimed, running, done, failed, cancelled, needs-review
runningqueued, running, done, failed, cancelled, needs-review
needs-reviewneeds-review, done, failed, cancelled
donedone, cancelled
failedfailed, cancelled
cancelledcancelled
dead-letterdead-letter

Who can do what

Registration checks that the declared kind matches the runtime, so an opencode process cannot register as claude.

What happens when a worker asks for work

At claim time the bus enforces kind affinity, required capabilities, host scope, dependencies between jobs (a DAG) and cost tier.

Submit a job

Use your own bus address in place of <bus-host>. Workers then poll the bus and claim the job themselves.

curl -s -X POST 'http://<bus-host>:5005/v1/jobs' \
  -H 'Content-Type: application/json' \
  -d '{
    "submitter_urn": "urn:agent:human:myhost:<session_uuid>",
    "kind": "code",
    "description": "fix the flaky parser test",
    "repo": "owner/repo",
    "head_branch": "fix/flaky-parser",
    "eligible_kinds": ["zeroclaw"],
    "priority": 0
  }'

Storage and connectors

Hive and MNEMOS

Hive works without MNEMOS: jobs are still queued, picked up, checked and merged. We strongly recommend running them together, because MNEMOS is where the stack keeps its memory. To connect them, set MNEMOS_URL and MNEMOS_TOKEN where the Hive workers run. A worker that has both adds a note to each job's brief that tells the coding agent to search for what earlier attempts on that job found and to record its progress as it goes. Hive reads those saved notes to work out why a job ended, its dashboard shows the status of every MNEMOS server, and one connector gives an agent both through a single MCP server. Without MNEMOS, every attempt starts from its brief alone, and nothing is remembered between attempts or sessions.

Settings

All the settings an operator can change, such as HIVE_URL, the bus tokens, the fleet inventory, the doctor's model endpoints and MNEMOS, are listed in one place: ENVIRONMENT.md. No address has a built-in default. Where a setting is unset, the feature it controls is turned off with one log line, not guessed.

Code and documents

Hive is a Python project and needs Python 3.11 or newer.

See the list of all repositories for the other projects in the group.

Licensing