---
title: Fork and replay
description: Replay a finished run step by step, and start a new task that
  continues a run from any step, with another instruction, model or version.
url: https://hexelstudio.com/docs/harness/fork-and-replay
---

**Steps.** Step `n` of a run is its `n`-th model call; step 0 is everything before the first.

## Replay a run

```bash
hexel harness replay run_789
hexel harness replay run_789 --from-step 5 --to-step 9
```

`GET /harness/runs/{id}/replay?from_step=&to_step=&after=&limit=` returns a finished run's stored events from `from_step` (default 0) to `to_step` (default the last), in order, each with its `step`:

```json
{"run_id": "run_789", "task_id": "tsk_123", "steps": 12, "from_step": 5, "to_step": 9,
 "events": [{"seq": 41, "step": 5, "type": "tool.call", "data": {}}], "next_after": 57}
```

- A run that has not ended is refused with `409 run_not_ended`.
- Only the run's own events are returned; a sub-agent is a run of its own.
- At most `limit` (1 to 1,000) events per answer; pass `next_after` as `after` for the next page.
- The events are what the control plane stores, so they are metadata only ([Content and history](https://hexelstudio.com/docs/harness/tasks#content-and-history)). The content is in the run's record in your runtime.

## Fork a run

A fork is a new task that continues a run from the end of one of its steps, optionally changed.

```bash
hexel harness fork run_789 --step 7 --instruction "Use the staging database instead"
hexel harness fork run_789 --step 7 --model anthropic/claude-sonnet-5-5 --follow
```

`POST /harness/runs/{id}/fork` takes `{step, instruction?, model?, version?}`:

| Field | Description |
| --- | --- |
| `step` | 0 to the run's steps. Past them: `400 step_out_of_range`. |
| `instruction` | Optional. The fork's goal: an extra instruction after the copied conversation. |
| `model` | Optional. `provider/model`; it must be the model or one of the `fallback_models` the version's bundle names (`400 model_not_allowed` with `details.allowed`). |
| `version` | Optional. Another version of the agent in your environment. |

The answer is the new task (`201`). Its first event after `task.state` is `run.forked` `{parent_run_id, step, overrides}`, and `GET /harness/tasks/{id}` shows its `fork`.

### What a fork is

- **A copy of the conversation up to the step**: messages, the model's turns and the tool results. Nothing is run again.
- **Nothing is inherited**: no policy decision, approval, budget or sandbox. The fork has its own Titan session and every action after the fork point is decided by Titan again. Its sandbox is new: the parent's files are not copied, and the model is told so.
- **Its own task**: yours, in the same workspace and environment, with the parent task's budget and sandbox template, admitted and billed like a new task. The copied turns are not billed again. Its own steps count from 1.
- **Its own retention**: a fork is not deleted with its parent; delete it on its own.
- **As careful as its parent**: the fork carries the parent's sensitivity, so Titan still asks before external side effects where the parent would have.

### Who can fork

You need `harness:task:read` and `harness:task:create`, and you must be able to see the run's task. Only a task's root run can be forked: a sub-agent's run is refused (`400`), and a swarm member's (`409 swarm_member`).

A fork is also refused (`409`) when the parent task is under a legal hold (`parent_held`), its content is erased (`parent_erased`), it is in a zero-retention environment or has a zero-retention run (`parent_zero_retention`), or its budget does not validate (`parent_budget_invalid`). A fork whose parent is held, erased or deleted before the fork starts fails with that reason as its `end_reason`.

The fork's start fails, naming why, when a tool call at or before the step has no result yet: it would have to run again.
