Skip to main content
Quickstart | MetaharnessQuickstart in the source-owned Metaharness documentation.Metaharnesshow-tometaharnesshow-toevaluatordeveloperresearcherbuild-agent-systemsinstall

Quickstart

Three of the four verbs below need no model, no network and no credential. Start with those: they tell you whether the seam is wired before you spend anything on a live run.

Build​

git clone git@github.com:beyond10x/metaharness.git
cd metaharness
cargo build --release

The workspace gate — format, lint, test — is one task:

task check     # cargo fmt --check && cargo clippy -D warnings && cargo test --workspace

Nothing under evals/ runs in task check. A paid run is never part of a gate.

AEP-governed workflows​

Metaharness 0.7.0 hosts model-backed AEP workflows through metaharness aep drive. AEP supplies the governor, planning commands and retained run storage; Harness supplies the native agent loop. The AEP CLI refuses model-backed maps before allocating a run and names this host.

From an AEP project with its task and step map already configured, inspect the command and run state first:

metaharness aep drive run --help
aep drive status

Starting a model is an explicit paid operation. Supply the plugin directory you intend to load and both spend bounds:

METAHARNESS_LIVE=1 metaharness aep drive run --project . --map development/default \
  --plugin-dir /path/to/agentplugins/plugins/aep-plan --pause-on-approval \
  --budget-usd 10 --assume-usd-per-run 1

Use metaharness aep drive resume RUN_ID with the same live opt-in for a compatible paused model-backed run. A resume may narrow its recorded budget, never raise it. Use --aep-binary when the planning executable must be selected explicitly. Live evaluation is metaharness aep drive eval run; aep drive eval run --stream reads recorded evidence offline. See the AEP integration guide for step maps, operator pauses and native transition hooks.

1. Is the installed vendor the one the adapter was written against?​

metaharness doctor claude
metaharness doctor codex

Every adapter claim about a vendor binary is pinned to a version. doctor compares the installed binary against that pin. During a run, --strict-version turns a mismatch from a warning into a refusal before anything spawns.

2. What does the adapter say it can do?​

metaharness capabilities claude
metaharness capabilities claude --render

Declared tiers, pinned versions, and — with --render — the neutral-operation → vendor-tool table. This exists so an embedder can refuse early rather than discovering mid-run that a tier is absent.

3. Does the seam actually hold?​

metaharness conformance claude    # 24 vectors
metaharness conformance codex     # 17 vectors, 4 of which run a real process and the real hook

Free conformance vectors: no model, no network, no credential.

4. A real run​

metaharness run claude --hermetic -p "list the crates in this workspace"

What happens:

  1. claude is spawned into a scratch config home — not yours.
  2. A blocking PreToolUse hook is installed, and metaharness answers it per call.
  3. The session streams out of stdout as protocol events, one JSON object per line.
  4. Steering commands are read from stdin, one JSON object per line.
  5. The raw vendor transcript is retained for the auditor.
  6. The process exits on the hermetic floor's verdict.

Deciding each call yourself​

metaharness run claude --hermetic --decisions ask -p "…"

With --decisions ask, every tool call arrives as a tool.requested event carrying decision_required: true, and the run blocks until you answer with tool.decide. See the control seam.

Governing a run from outside the process​

metaharness run claude --hermetic --frame step.frame.json -p "…"

The frame is a sealed metaharness.frame/1 document: digest-verified on load and enforced from the first turn. This is the seam an external driver integrates through — it writes the frame as a file and never links this workspace.

Running over a real repository​

metaharness run claude --hermetic --cwd ~/projects/thing -p "…"

--cwd is the declaration that trades two hermetic rows for real work: the child runs in your tree and can write to it, so H7 and H11 stop being impositions and are attested unavailable, naming the directory. The vendor sandbox is widened to that tree for the run — on codex, sandbox_mode = "workspace-write" — and the H7 attestation row states the grant in words, so the run's own record says it could change your repository. --hermetic strict therefore refuses such a run, plain --hermetic reports it honestly. A scratch-cwd run writes nothing, anywhere.

Exit codes​

CodeMeaning
0The run completed and every gating hermetic row is ok.
1A gating row is gap — a control did not hold.
2Refused: a verb or option that is not built, naming what it waits for.
3A gating row is unk — nobody found out. Not a softer gap.