hiveloomdocs

Introduction

Confine an agent to one job — and make success provable.

An agent is a model plus its harness. hiveloom turns the harness for a repeatable task into a self-contained folder: the task, tools, context, budgets, stopping rules, and validators. A human or a capable coding agent can declare that boundary; a smaller model can then execute inside it repeatedly. The runtime decides whether the result counts as success.

Released: 1.2.0 (25 September 2026), installable with uv tool install "hiveloom==1.2.0". The spec, CLI, Python SDK, runtime, journal/Hive memory, generation, gated and signal-driven evolution, packaging, MCP integration, delegation between harnesses, and HTTP serving surfaces are implemented, along with playbooks, structured artifacts, run control, run-scoped notes and durable memory, and a tamper-evident run journal you can fork from, replay, and read in the workbench.

New in 1.2.0

The signal, memory and collaboration release. Full details in the release notes.

  • Evolution finds the signal before it proposes. hiveloom signal contrasts failing and successful runs feature by feature, counts the mechanisms a change would be judged by, and says how much the sample can show — for free, before any model call. Every proposal then names the signal it aims at and predicts how it will move; hiveloom assess checks that prediction against the runs that follow, and evolve --experiment keeps a change only when an eval confirms it. See Signal-driven evolution.
  • Memory that scales and learns. Durable lessons live in harness.yaml and reach it only through reviewed proposals; with memory.selection: relevant each run sees only the lessons that match its task. Reflection drafts lessons from failed runs for review. Run-scoped notes survive compaction, and transform_result narrows large stored results in place.
  • Delegation between harnesses. A harness hands a task to a peer that has earned it in measured runs — locally or over MCP — verifies the answer with its own validators, and otherwise names the peer as a referral. See Delegation.
  • Runs that recover. Truncated turns continue within declared budgets, transient provider failures are retried, and compaction carries the previous summary forward instead of re-summarizing it.
  • Ten demo harnesses as proof. Each one states what it proves and the evidence to look for; four run offline with no API key. See Demo harnesses.

Upgrading from 1.1.0: a proposal from evolve or auto-propose must now name a target from the signal map (a model or script emitting the old proposal shape needs the field), and a guardrail-blocked output is never returned, even when a run exhausts its turns — see release notes.

The product is the boundary

The harness confines How
Purpose One task and one system prompt travel with the harness.
Capabilities Only declared tools, skills, playbooks, MCP servers, and registered peers enter the loop.
Autonomy Turn, time, cost, context, and tool policies bound execution.
Acceptance Deterministic validators — not the model — decide whether an answer counts as success.
Change Evolution is limited to declared mutable fields, aimed at measured signal, and checked against its own prediction; safety-critical fields stay frozen.
Evidence Every run is tied to the exact harness version and written to a checkable journal.

This is task confinement, not a claim that arbitrary code runs in a virtual machine. It makes a harness more reliable than a prompt and narrower than a general-purpose agent.

The interface is agent-native on both sides: builder agents inspect the schema and catalog and drive the JSON-speaking construction CLI; calling agents use a finished harness through MCP and receive a structured, validator-checked result.

Where to go next

If you want to Read
Get it running in five minutes Install then Quickstart
See each capability proven on a small task Demo harnesses
Understand the product boundary Task confinement
Build one without learning the CLI first The workbench
Know whether a harness actually helps Evaluations
Measure one on your own dataset Local evaluations
Improve one from evidence, and prove the change Signal-driven evolution
Let harnesses hand work to each other Delegation
Understand every field in harness.yaml Harness spec
See how the runtime fits together Architecture
Debug a failed run at the turn it went wrong Journal and forks
Point a harness at a different lab Models and providers
Add your own tools or providers Extending
Ship and keep improving it Deploying and evolving
Drive a served harness over HTTP Control plane

Two ways in

The CLI builds a harness through one validated construction path — init, add, set, validate, run — and every command speaks --json, so it scripts cleanly. Start at the Quickstart.

The workbench is the same framework with a face: a chat-first development UI where you talk to a copilot that creates, validates, runs, and diagnoses harnesses for you, with the exact framework state — spec, runs, the full journal of any one of them, version comparisons, pending proposals — open beside the conversation. It is the fastest way to see what a harness actually did, and the only comfortable way to read a long run back.

Safety invariants

  • Evolution can never change id, guardrails, model, logging.redact, extensions, hooks, mcp_servers, confinement, egress, evolution.auto_propose, evolution.reflect, evolution.trace_excerpts, evolution.objectives, or the memory budgets.
  • The executor never writes durable memory; lessons reach harness.yaml only through a reviewed proposal.
  • A guardrail-blocked output is never handed back to the caller.
  • The cost guardrail defaults on at $1.00.
  • The shell tool is disabled unless explicitly configured and remains allowlist-only; spawned processes are confined.
  • Redaction runs before trace persistence, and provider egress is screened.
  • Foreign harness code is trust-gated before loading; a delegation peer is offered only once trusted.

Apache-2.0 licensed. Source at github.com/FrancescoMrn/hiveloom.