---
name: record-agent-video
description: Record, publish, share, and respond to feedback on desktop video evidence for an AI agent run.
---

# Record agent onboarding

Record is a desktop recording CLI and review platform for AI agents. Use it when a human wants visual evidence of a task, a replayable demonstration, timestamped feedback, or an approval decision.

## Install and verify

```sh
npm install --global <https-origin>/downloads/record-cli.tgz
record-cli --version
record-cli doctor --json
```

`doctor` must report that a supported capture backend exists. On macOS, ask the human to grant Screen Recording permission if the check fails. Do not attempt to bypass operating-system permission prompts.

## Authenticate safely

Prefer a named, scoped agent credential created from the workspace's **Connect agent** page. Never request or store an administrator workspace token when a scoped token is available.

Run the human-provided setup command once:

```sh
record-cli connect --server <https-origin> --token <rec_pat_…> --name <agent-name> --json
```

It stores the HTTPS workspace origin and scoped `rec_pat_…` credential in a private configuration file for the current OS user.

Do not print the token in logs, commit it to source control, place it in recording metadata, or include it in a shared video.

Verify remote access before recording:

```sh
record-cli list --json
```

## Choose the correct path

| Goal | Path |
| --- | --- |
| Capture a bounded visual task | Start a timed recording, perform the task, then publish |
| Capture another agent command | Use `record-cli run -- <command>` |
| Expose progress while working | Start with `--server`, then add `record-cli mark` milestones |
| Publish an existing video | Use `record-cli publish <file>` |
| Read human feedback | Use `record-cli inbox` and `record-cli show` |
| Send a reviewer one run | Use `record-cli share <recording-id>` |

When the human asks for constrained sharing, use `--permissions view,comment,review`, `--expires 1d|7d|30d|never`, `--disable`, or `--rotate`. Never broaden an existing link's permissions without being asked.

Local capture is unlimited and remains on the machine until publication succeeds. Hosted workspaces include a cloud allowance. If publication returns `WORKSPACE_QUOTA_EXCEEDED` or `CLOUD_READ_ONLY`, do not delete or move the local file. Report its `localPath`, the usage details, and the supplied `upgradeUrl` to the human. Existing cloud recordings and local capture remain available.

## Record a bounded task

Start recording before the visual work begins:

```sh
record-cli start \
  --duration 10 \
  --title "Homepage scan" \
  --agent "codex" \
  --task "Show the requested website and verify its visible state" \
  --json
```

Perform only the authorized task. Avoid displaying unrelated tabs, notifications, credentials, personal messages, or private data.

Add milestones when they make the replay easier to review:

```sh
record-cli mark "Opened target page" --kind action --json
record-cli mark "Verified final state" --kind milestone --json
```

If the duration does not finalize automatically, stop and publish:

```sh
record-cli stop --publish --json
```

The final JSON result should include a recording ID and URL. Return the share URL to the human, not a local filesystem path.

## Record an agent command

Use this when the visual work is launched by a single command:

```sh
record-cli run \
  --title "Checkout QA" \
  --agent "codex" \
  -- node agent.js
```

The child command receives a short-lived run token for event ingestion. Do not replace it with the workspace or agent token.

## Read and act on feedback

Poll the durable activity cursor:

```sh
record-cli inbox \
  --type feedback.* \
  --json
```

Inspect one recording:

```sh
record-cli show <recording-id> \
  --json
```

Treat open issues and questions as work items. After correcting an issue, reply with the evidence and resolve it only when the requested change is genuinely complete. Approval is blocked while actionable feedback remains open.

## Recovery

- `SCREEN_RECORDING_PERMISSION_REQUIRED`: ask the human to grant permission and rerun `doctor`.
- `UNAUTHORIZED`: ask the human to reconnect this agent or rotate its scoped credential.
- `FORBIDDEN`: the token lacks a required scope; ask for the smallest additional scope.
- `RUN_CLOSED`: create a new run; do not reuse an expired run token.
- Upload interruption: rerun publish with the same file and metadata. Do not delete the local recording until remote publication is confirmed.
- Human unavailable: record locally, retain the file safely, and report that publication is pending authorization.

## Safety rules

1. Record only after the human requests visual evidence or the workflow explicitly requires it.
2. Keep the recording duration and display scope as narrow as practical.
3. Do not enable microphone capture unless the human asked for audio.
4. Never expose Record credentials, browser passwords, API keys, or unrelated private content.
5. Verify remote publication before claiming the video is available.
6. Provide the final review URL and a short description of what the recording demonstrates.

## References

- Human getting started: `/docs/agents`
- CLI reference: `/docs/cli`
- Reviewer guide: `/docs/reviewers`
- Security model: `/docs/security`