Take one coding task from prompt to reviewed patch

Before you start

Use a Git repository with a clean enough baseline that you can recognize the agent's change. You do not need Podman or a microVM runtime for the first box. h5i can use its lightweight host-kernel tiers when the operating system supports them.

Choose one agent runtime. The guide shows Claude Code; Codex works the same way with the runtime-specific profile and command changed. One runtime per box keeps HOME state, API routing, and credential handling narrow.

1. Install h5i and check the host

Install the single binary, then ask it what this machine can actually enforce. probe performs a functional check; it does not infer support from the operating-system name.

$ curl -fsSL https://h5i.dev/install.sh | sh
$ h5i box probe
$ h5i skill install

The skill teaches a supported coding agent how to operate the box. It is embedded in the binary, so its commands match the version you installed.

2. Create a box from the current repository

$ h5i box create first-box --from HEAD --profile agent-claude
$ h5i box status first-box

Creation freezes the base revision and resolves the policy before the workspace exists. Read the status once. It names the isolation tier, filesystem grants, network policy, resource limits, and policy digest that the receipts will carry.

Do not skip that output on the first run. Find the answers to four questions: which tier was selected, whether the box shares the host kernel, which paths are writable, and how network access is scoped. The point is to verify the claim before asking the agent to do useful work.

box       first-box
base      <frozen commit>
profile   agent-claude
isolation <resolved tier>
policy    sha256:<digest>
write     $WORK only

3. Work inside the boundary

$ h5i box shell first-box
box$ claude
# Ask for one concrete change. Let the agent edit, build, and test.
box$ exit

shell is the boundary. Every child process inherits it, including package scripts and test runners. You do not need to remember to wrap each command.

For a single deterministic check, skip the interactive shell:

$ h5i box run first-box -- cargo test
$ h5i box run first-box -- npm test

4. Inspect before you export

$ h5i box diff first-box --stat
$ h5i box diff first-box
$ h5i box log first-box
$ h5i box status first-box

Use the diff to review the result and the log to review the execution. They answer different questions. A clean patch does not prove that tests ran; a successful test does not make an unrelated edit acceptable.

5. Move the result through the output gate

$ h5i box export first-box --out ./review-first-box
$ git apply --check ./review-first-box/patch.diff
$ less ./review-first-box/report.md

The export contains patch.diff, report.md, and receipt.json. The patch is path-validated. The report puts denied egress and failed execution ahead of the agent's own proposal.

If this is a local box and you want h5i to land the work directly, freeze it first:

$ h5i box propose first-box
$ h5i box apply first-box

6. Remove the box when the decision is made

$ h5i box rm first-box
$ h5i box gc

A box is cheap because it is disposable. Keep the export. Remove the execution environment.

If the first run fails

The requested tier is unavailable

Run h5i box probe and read the reason. An explicit tier fails rather than falling back. Either satisfy the prerequisite or choose a tier whose stated boundary fits the task; do not translate refusal into “turn security off.”

A build cannot download dependencies

The default profile may have no network. Add only the registry destinations the build needs in a repository profile, or prepare a read-only warm cache. A denied telemetry endpoint is not automatically a missing dependency.

The agent cannot find its login

Check that the profile matches the runtime and run h5i box secrets first-box. It shows resolution state without printing values. Do not solve the problem by copying a whole host HOME into the box.

Apply refuses

Only local worktree boxes can use the mediated propose/apply path. Boxes created from a pull request, clone URL, or empty repository are detached; export the patch and apply it explicitly where you want it.

What “done” looks like

Your first run is successful when you can explain the boundary and the result separately. You should know which tier ran, which test exits were observed, which destinations were denied, and which exact patch you are choosing to take. The agent's summary is helpful, but none of those answers should depend on trusting it.

Reference

• Installation and skill setup.
• The complete box command reference.
• Export bundle semantics and review order.
• Why the complete environment is the isolation unit.

Questions that come up