# 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.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](/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](/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](/evaluating).
- **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](/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](/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) |
| Measure one on your own dataset | [Local evaluations](/evaluating) |
| 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).