# hiveloom

**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.0.0`, now 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](/workbench).

## 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](/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](/install) then [Quickstart](/quickstart) |
| Understand the product boundary | [Task confinement](/task-confinement) |
| Build one without learning the CLI first | [The workbench](/workbench) |
| Know whether a harness actually helps | [Evaluations](/evals) |
| Understand every field in `harness.yaml` | [Harness spec](/spec) |
| See how the runtime fits together | [Architecture](/architecture) |
| Debug a failed run at the turn it went wrong | [Journal and forks](/journal) |
| Point a harness at a different lab | [Models and providers](/models) |
| Add your own tools or providers | [Extending](/extending) |
| Ship and keep improving it | [Deploying and evolving](/deploying-and-evolving) |
| Drive a served harness over HTTP | [Control plane](/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](/quickstart).

**[The workbench](/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](https://github.com/FrancescoMrn/hiveloom).