Trace and fork

holmd records what is done to each box in a trace. You can read the trace to see what happened, and fork a box to make a new box that does the same steps again.

Traces and forks need a server. The Rust library with no server has no trace. See The server.

What the trace records

Each entry has a sequence number (seq), a time (at_ms), an actor, an event, and sometimes a frame hash.

What is not recorded

• A person's input. It goes to the box over VNC, so the server does not see it. The trace records only the period when the person had the screen. The frames in that period show what changed.
• Page actions outside a batch. holm browser commands and the MCP page tools (click_element, fill_field, dropdown, and others) are not in the trace. Page actions inside an action batch are. See Make a run that you can fork.
• Reads. read, snapshot, find, and evaluate through their own endpoints are not recorded.

The actor of a frame entry is the one that had the screen when the frame was captured, not the one that changed it. A frame is recorded only when the screen changed, so a still screen adds no entries. No frame entry between takeover_started and takeover_ended means that nothing visible changed during the takeover.

Read the trace

holm trace "$BOX"
holm trace "$BOX" --after 40

   0  agent    created 1280x800
   1  agent    screen 0  open_url
   2  agent    screen 0  the screen changed
   3  agent    screen 0 handed to a person
   4  person   screen 0  the screen changed
   5  agent    screen 0 taken back
   6  agent    ran ls /tmp → 0

REST:

curl -s "$BASE/v1/boxes/$BOX/trace?after=12&limit=100"
curl -s "$BASE/v1/boxes/$BOX/trace/frames/$HASH" -o frame.png

The response has entries and next. To read more, send next as after. A page has at most 500 entries.

A trace stays after its box is removed.

Make a run that you can fork

A fork does again only some of what the trace has:

To make page actions part of a run that you can fork, put them in a batch:

cat > steps.json <<'JSON'
[
  { "type": "open_url", "url": "https://example.com/order" },
  { "type": "on_page", "what": { "op": "fill", "query": "Name", "text": "Ada" } },
  { "type": "on_page", "what": { "op": "click", "query": "Continue" } },
  { "type": "on_page", "what": { "op": "wait_for", "query": "Details" } }
]
JSON
holm batch "$BOX" steps.json

MCP: the batch tool, with steps such as fill_field and click_element.

Each step of a batch becomes its own acted entry.

Fork a box

NEW=$(holm fork "$BOX")
NEW=$(holm fork "$BOX" --up-to 40)

REST:

curl -s -X POST "$BASE/v1/boxes/$BOX/fork" \
  -H 'content-type: application/json' \
  -H 'idempotency-key: fork-1' \
  -d '{"up_to": 40}'

MCP: fork_box. It forks the full trace. It has no up_to or placement.

The server:

1. Reads the spec and placement from the box_created entry.
2. Creates a new box on the same runtime, unless your placement names another. The new box does not get the source's browser profile.
3. Records box_created and forked_from in the new trace.
4. Does the recorded steps again, in order, at about the original speed. A wait between two steps is at most 2 seconds.
5. Captures a frame at the end.

You can fork a box that was removed, because its trace stays.

The result

{
  "box": { "id": "box_…", "state": "ready" },
  "replay": {
    "attempted": 3,
    "ok": 3,
    "truncated": false,
    "skipped": [
      { "seq": 2, "kind": "file_written", "why": "the trace records that /tmp/marker.txt was written, not what went into it" }
    ]
  }
}

The CLI prints the new box ID. The new box stays, even when the replay stopped early.

Why a fork can be different

A fork does the steps again. It does not copy memory or disk. The result can differ from the source because:

• The page can be different now.
• The network and page timing can be different.
• A dialog or a popup can appear this time and not the first time.
• Animations make two screens of the same state look different.

Compare the last frame of each trace if you must know how close the fork is.

What the fork does not do again:

Keep traces across restarts

The default memory store loses all traces when the server stops. It also keeps at most 10,000 entries and 256 frames for each box, and traces for at most 256 boxes.

After a restart with the memory store, the server takes its boxes back, but each trace starts again with adopted. A fork of such a box does only the steps after the restart.

Use a durable store to keep traces:

HOLM_STORAGE_BACKEND=local HOLM_STATE_DIR=/var/lib/holm holmd

A fork needs the frames only for comparison, not to replay, so old frames can go before the entries. See Storage.