> ## 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.

# Record the screen

> Record the display and hand control to a person

Record the screen and what was clicked, then decide who drives the live view: the agent, a person, or both.

## Record what happens

`start_recording` returns `rec_id`, `status`, `bytes`, and `duration_ms`. `include` chooses what to record. Omit it to record everything:

| Component | Captures |
| - | - |
| `video` | The display as MP4 |
| `input` | Pointer and keyboard events (trajectory) |
| `window` | Window open/close/focus events |
| `app` | Application launches and exits |

`window_id` records one window. `0` records the whole screen. `label` is a name you can filter on later. `dir` overrides where the MP4 and trajectory artifacts land in the guest — an absolute path, created if missing; omit it for the platform default. Download the MP4 with `recording_video` (`recordVideo` in TypeScript) — it is playable while the recording is still running.

The trajectory JSONL records input events and marks — sensitive text is
represented by length/redacted metadata, never verbatim keystrokes.

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

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()

rec = sandbox.desktop.start_recording(include=["video", "input"], label="run-1")
rid = rec["rec_id"]

# ... drive the desktop ...

sandbox.desktop.mark_recording(rid, "checkpoint")
sandbox.desktop.stop_recording(rid)

meta = sandbox.desktop.recording(rid)
print(meta["status"], meta["bytes"], meta["duration_ms"])
open("recording.mp4", "wb").write(sandbox.desktop.recording_video(rid))

sandbox.desktop.delete_recording(rid)
```

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

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();

const rec = await sandbox.desktop.recordStart({ include: ['video', 'input'], label: 'run-1' });

// ... drive the desktop ...

await sandbox.desktop.recordMark(rec.recId, 'checkpoint');
const done = await sandbox.desktop.recordStop(rec.recId);
console.log(done.status, done.bytes, done.durationMs);
const mp4 = await client.runtime.desktop.recordVideo(sandbox.runtimeId, rec.recId);
console.log(mp4.byteLength);

await sandbox.desktop.recordDelete(rec.recId);
```

```bash CLI theme={null}
REC=$(gravixlayer runtime desktop record-start "$RT" \
  --include video --include input --label run-1 --output json | jq -r .rec_id)

# ... drive the desktop ...

gravixlayer runtime desktop record-mark "$RT" "$REC" checkpoint
gravixlayer runtime desktop record-stop "$RT" "$REC"

gravixlayer runtime desktop recording "$RT" "$REC"
gravixlayer runtime desktop record-download "$RT" "$REC" recording.mp4
gravixlayer runtime desktop record-download "$RT" "$REC" trajectory.jsonl --artifact trajectory

gravixlayer runtime desktop record-delete "$RT" "$REC"
```

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

REC=$(curl -sS -X POST "$API/agents/runtime/$RT/display/recordings" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include":["video","input"],"label":"run-1"}' | jq -r .rec_id)

# ... drive the desktop ...

curl -sS -X POST "$API/agents/runtime/$RT/display/recordings/$REC/mark" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"checkpoint"}'

curl -sS -X POST "$API/agents/runtime/$RT/display/recordings/$REC/stop" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS "$API/agents/runtime/$RT/display/recordings/$REC" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS "$API/agents/runtime/$RT/display/recordings/$REC/video" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -o recording.mp4

curl -sS "$API/agents/runtime/$RT/display/recordings/$REC/trajectory" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -o trajectory.jsonl

curl -sS -X DELETE "$API/agents/runtime/$RT/display/recordings/$REC" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

`recordings` lists every recording — active first, then completed
newest-first. An input-only recording (`include: ["input"]`) produces a
trajectory without a video path.

## Hand control to a person

`set_control_mode` sets the live-view takeover mode, also reported as
`control_mode` on `desktop.status`/`desktop.info`:

| Mode | Effect |
| - | - |
| `shared` | Default — the agent and any human viewer may both send input |
| `human` | Only the human viewer drives; agent input (`click`, `type`, `act`, a11y actions) is rejected |
| `agent` | Only the agent drives |

While the mode is `human`, input calls return `400`; screenshots,
snapshots, and status keep working so the agent can still observe.

```python Python theme={null}
sandbox.desktop.set_control_mode("human")   # hand the session to the viewer
sandbox.desktop.click(640, 360)             # -> 400 while human owns input
sandbox.desktop.set_control_mode("shared")  # restore shared control
```

```typescript TypeScript theme={null}
await sandbox.desktop.viewControl('human');   // hand the session to the viewer
// input calls are rejected while a human owns input
await sandbox.desktop.viewControl('shared');  // restore shared control
```

```bash CLI theme={null}
gravixlayer runtime desktop view-control "$RT" human    # hand the session to the viewer
gravixlayer runtime desktop view-control "$RT" shared   # restore shared control
```

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

curl -sS -X POST "$API/agents/runtime/$RT/display/view/control" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"human"}'

curl -sS -X POST "$API/agents/runtime/$RT/display/view/control" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"shared"}'
```

Pair this with a [live view](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/screen.md#watch-the-screen-live)
URL: mint the view, switch to `human` so the operator can intervene, then
return to `shared` when they hand control back.

## Endpoints

| Method | Path | Description |
| - | - | - |
| POST | `/v1/agents/runtime/{runtime_id}/display/recordings` | Start a recording |
| GET | `/v1/agents/runtime/{runtime_id}/display/recordings` | List recordings |
| GET | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}` | One recording's metadata |
| POST | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}/stop` | Finalize a recording |
| POST | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}/mark` | Stamp a named mark |
| DELETE | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}` | Delete a recording |
| GET | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}/video` | Download the MP4 |
| GET | `/v1/agents/runtime/{runtime_id}/display/recordings/{rec}/trajectory` | Download the event log |
| POST | `/v1/agents/runtime/{runtime_id}/display/view/control` | Choose who can click |


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