> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Replay and fork

> Replay a recorded action sequence, or clone the session into parallel workers

Two ways to multiply one session: `replay` re-runs a recorded action sequence through the real action pipeline (with per-step effect checks), and `fork` clones the live browser into up to 8 parallel targets so a cohort can fan out from the same state.

CLI and cURL examples use `$RT` and browser `b1` ([Sessions](https://docs.gravixlayer.ai/documentation/agentruntime/browser-use/browser.md)).

## Replay a sequence

`replay` takes `steps` — `[{action: {verb, target, …}, expect_*}]` entries,
where `action` is the same body `actions/{verb}` accepts — and runs each
through the real action pipeline. After every step's settle it can check
`expect_url_contains`, `expect_selector` (a CSS that must resolve), or
`expect_eval` (JS that must eval truthy). `stop_on_fail` halts at the first
mismatch, `step_timeout_ms` caps each step, and `target_id` replays into a
specific tab; the reply carries `{ok, steps_run, results}`.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()  # reads GRAVIXLAYER_API_KEY
sandbox = client.runtime.create(template="browser-small")
bid = sandbox.browser.open(url="https://example.com/form")["browser_id"]

r = sandbox.browser.replay(bid, [
    {"action": {"verb": "fill", "target": {"by": "ref", "value": "e3"},
                "text": "ada@example.com"}},
    {"action": {"verb": "click", "target": {"by": "ref", "value": "e7"}},
     "expect_url_contains": "/thanks"},
], stop_on_fail=True)
print(r["steps_run"], [s["ok"] for s in r["results"]])
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'browser-small' });
const bid = (await sandbox.browser.open({ url: 'https://example.com/form' })).browserId;

const r = await sandbox.browser.replay(bid, [
  { action: { verb: 'fill', target: { by: 'ref', value: 'e3' },
              text: 'ada@example.com' } },
  { action: { verb: 'click', target: { by: 'ref', value: 'e7' } },
    expect_url_contains: '/thanks' },
], { stopOnFail: true });
console.log(r.steps_run, r.results);
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime browser replay "$RT" --browser b1 --stop-on-fail --steps '[
  {"action": {"verb": "fill", "target": {"by": "ref", "value": "e3"},
              "text": "ada@example.com"}},
  {"action": {"verb": "click", "target": {"by": "ref", "value": "e7"}},
   "expect_url_contains": "/thanks"}
]'
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/replay" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{"action":{"verb":"click","target":{"by":"ref","value":"e7"}}}],
       "stop_on_fail": true}'
```

## Fork the session

`fork` clones the browser's current state into `count` new tabs (1–8) and
returns their target ids — a worker cohort that starts from identical cookies,
DOM, and scroll position. Pass `url` to point every fork somewhere new; omit
it to keep each clone on the page it forked from.

```python Python theme={null}
cohort = sandbox.browser.fork(bid, count=4, url="https://example.com/queue")
print(cohort["target_ids"])   # ["t2", "t3", "t4", "t5"]
# Hand each target_id to a worker — each is an independent tab.
```

```typescript TypeScript theme={null}
const cohort = await sandbox.browser.fork(bid, {
  count: 4,
  url: 'https://example.com/queue',
});
console.log(cohort.target_ids); // ['t2', 't3', 't4', 't5']
```

```bash CLI theme={null}
gravixlayer runtime browser fork "$RT" --browser b1 \
  --count 4 --url https://example.com/queue
```

```bash cURL theme={null}
curl -sS -X POST "$API/agents/runtime/$RT/browser/b1/fork" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 4, "url": "https://example.com/queue"}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.