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.1.0, installable with uv tool install hiveloom. The spec, CLI, Python SDK, runtime, journal/Hive memory, generation, gated evolution, packaging, MCP integration, and HTTP serving surfaces are implemented, along with playbooks, structured artifacts, run control, and a tamper-evident run journal you can fork from, replay, and read in the workbench.

New in 1.1.0

The containment and evidence release.

  • Nothing is truncated away. A tool result over the inline budget is stored whole beside the journal and replaced in context by a preview and a handle, so the model can read or search the omitted part instead of losing it.
  • A harness can consult its own history mid-run. The recall_runs tool surfaces this harness's earlier successes as worked examples and its failures with the verifier feedback that rejected them.
  • Spawned processes have an inspectable boundary. shell and command_succeeds run with a scrubbed environment, bounded output, resource limits, and — where the platform has a sandbox — kernel-enforced filesystem and network isolation. hiveloom confinement reports what a given machine can actually enforce. See Task confinement.
  • Evaluation is a first-class local contract. Versioned eval documents, dataset loaders, scorers, a resumable runner, reports, and paired comparisons — see Local evaluations.
  • Evolution reasons over recorded friction and metric objectives rather than raw failure counts.

Upgrading a harness that uses shell or command_succeeds is the one place 1.1.0 changes existing behavior: spawned commands no longer inherit the runtime's environment, network, or home directory. The knobs to restore each are in Task confinement.

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, and MCP servers 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; 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
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
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 cannot change guardrails, model, logging.redact, extensions, hooks, mcp_servers, or evolution.auto_propose.
  • The cost guardrail defaults on at $1.00.
  • The shell tool is disabled unless explicitly configured and remains allowlist-only.
  • Redaction runs before trace persistence.
  • Foreign harness code is trust-gated before loading.

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