# YoRecord Agent Shares — instructions for an AI agent

You are reading the complete integration. **Everything you need is on this page** — no
other page, no package, and no code of ours on this machine. Three HTTP requests.

**What this does:** you upload a video file you already have — a Playwright `recordVideo`
capture, a CI artifact, anything that is an MP4 — and you get back a URL your human can
click in the chat.

**What this does NOT do:** it does not record anything. If you have no video file, this
cannot help you.

**DO NOT INSTALL ANYTHING to use this.** Not a browser, not ffmpeg, not a package. Use what
this machine already has. If it has no browser automation, or no way to make an MP4, say so
and stop — that is a complete and useful answer. Installing build tools to share a video is
not what your human asked for.

**If a request is BLOCKED or the host is UNREACHABLE** — a 403 from a proxy, a domain
allowlist, a denied permission — **say so plainly and stop. Do not work around it.** Not
with another host, not with another tool, not by asking for a permission the human already
withheld. A blocked network is a fact to report, not an obstacle to solve.

**Before you upload, ASK YOUR HUMAN.** The link is public to anyone who has it, and that is
not reversible by wishing. One sentence is enough: what the recording shows, and that the
link will be public.

**If you record something yourself, use a FRESH browser profile.** Never the person's own —
their logged-in Gmail, Slack or Jira must never end up in a public video. A clean, throwaway
context, every time.

## The short version — your human can paste this instead of sending you here

<!-- PASTE-BLOCK-START -->
```
Set up YoRecord agent sharing and share a video with me. Do not install anything.

1. Ask for access:
   curl -sS -X POST https://up.yorecord.com/agent-tokens/device
   Show me the verification_url. Keep device_code to yourself.

2. Poll every 3s until I approve it in my browser:
   curl -sS "https://up.yorecord.com/agent-tokens/device?device_code=$DEVICE_CODE"
   Save the token to ~/.config/yorecord/token, chmod 600. It is returned once only.

3. Upload an MP4 you already have (a Playwright recordVideo file, a CI artifact, anything):
   SHARE_ID=$(uuidgen | tr 'A-Z' 'a-z')
   curl -sS -X PUT "https://up.yorecord.com/agent-shares/$SHARE_ID/rendered.mp4" \
     -H "Authorization: Bearer $(cat ~/.config/yorecord/token)" \
     -H "Content-Type: video/mp4" --data-binary @VIDEO.mp4
   Give me the url from the response.

Rules: MP4 only, 50 MB max, 10 uploads a day. Links are PUBLIC to anyone who has them and
are deleted after 7 days. My clicking Approve is my consent for this recording - do not ask
me again. If a request is blocked, tell me and stop; do not work around it. If this machine
has no MP4 and no browser automation already installed, tell me and stop.
```
<!-- PASTE-BLOCK-END -->

Everything below is the same three requests with the failure cases spelled out.

---

## Read this to your human before you upload anything

- **Anyone with the link can watch.** Uploads are not private. They are exactly as public
  as wherever the link gets pasted, and they are deleted automatically after 7 days.
- **Do not upload footage showing passwords, API keys, inboxes, customer records or
  anyone else's personal data.** If it should not be in a public gist, it should not be
  here. If something slips through, delete it (step 4) and it is gone.
- Say the link is public when you hand it over. Do not let a person discover that later.

---

## Step 1 — ask for access (first time on this machine only)

```bash
curl -sS -X POST https://up.yorecord.com/agent-tokens/device
```

```json
{
  "user_code": "FDZV-NKQ7",
  "device_code": "d3b306f1…",
  "verification_url": "https://yorecord.com/approve?c=FDZV-NKQ7",
  "interval_seconds": 3,
  "expires_in_seconds": 600
}
```

**Show the `verification_url` to your human and ask them to open it and press Approve.**
Say the code out loud in your message, so they can check it matches. Keep the
`device_code` to yourself — it is the secret half, it is how you collect the token, and it
must never appear in your message.

The code expires in 10 minutes.

## Step 2 — wait for the click, then collect the token once

```bash
curl -sS "https://up.yorecord.com/agent-tokens/device?device_code=$DEVICE_CODE"
```

Poll every 3 seconds. You will see `{"status":"pending"}` until they click, then:

```json
{ "status": "approved", "token": "yr_…" }
```

**The token is returned exactly once.** Save it immediately, readable only by the user:

```bash
mkdir -p ~/.config/yorecord && umask 077
printf '%s' "$TOKEN" > ~/.config/yorecord/token
chmod 600 ~/.config/yorecord/token
```

Other statuses: `expired` (start again at step 1), `collected` (somebody already took it),
`unknown` (wrong `device_code`).

**On a NETWORK ERROR rather than a status** — a timeout, a connection reset, a proxy 403 —
retry at most three times, a few seconds apart, then STOP and tell your human what you saw.
Do not poll indefinitely: the code expires in 10 minutes anyway, and a wall of retries hides
the real problem. Treat anything that is not `pending` or `approved` as a reason to stop and
report, never as a reason to try a different route.

In CI, do this once on a laptop and put the token in one secret named `YORECORD_TOKEN`.
There is no way to get a token without a human clicking, by design — an upload capability
that appears with no human act is a way for injected text to publish somebody's screen.

## Step 3 — upload a video

```bash
SHARE_ID=$(uuidgen | tr 'A-Z' 'a-z')
curl -sS -X PUT \
  "https://up.yorecord.com/agent-shares/$SHARE_ID/rendered.mp4" \
  -H "Authorization: Bearer $(cat ~/.config/yorecord/token)" \
  -H "Content-Type: video/mp4" \
  --data-binary @test-results/run.mp4
```

```json
{ "ok": true, "uid": "…", "url": "https://yorecord.com/view?uid=…", "expiresInDays": 7 }
```

Give your human the `url`. Nothing else is needed — it opens in any browser, with no
account and no download.

**MP4 only, and we check the actual bytes rather than the header.** Playwright records
WebM, so convert first:

```bash
ffmpeg -y -i video.webm -c:v libx264 -pix_fmt yuv420p run.mp4
```

Limits, and what each refusal means:

| Status | Meaning | What to do |
|---|---|---|
| `401` | No token, or this machine was never approved | Go to step 1 |
| `403` | The token was revoked | Ask your human |
| `413` | Over 50 MiB | Shorten the recording or lower the frame rate |
| `415` | Not really an MP4 | Convert it |
| `429` | 10 uploads today already | Tell your human the message verbatim; it says when it resets |
| `503` | Service storage is full | Not the human's fault; say so and try later |

## Step 4 — delete a share (any time before it expires)

```bash
curl -sS -X DELETE \
  "https://up.yorecord.com/agent-shares/$UID" \
  -H "Authorization: Bearer $(cat ~/.config/yorecord/token)"
```

Only the token that created a share can delete it.

---

## Optional — attach labelled steps

Upload a JSON sidecar next to the video and the viewer will be able to show a rail of
steps with jump-to-step. **Today it is stored but not yet displayed**, so treat it as an
investment rather than a feature.

```bash
cat > steps.json <<'JSON'
[
  { "t": 0,    "label": "Opened the checkout page", "status": "pass" },
  { "t": 12.4, "label": "Filled the card form",     "status": "pass" },
  { "t": 41.2, "label": "Clicked Pay",              "status": "fail" }
]
JSON

curl -sS -X PUT \
  "https://up.yorecord.com/agent-shares/$SHARE_ID/steps.json" \
  -H "Authorization: Bearer $(cat ~/.config/yorecord/token)" \
  -H "Content-Type: application/json" \
  --data-binary @steps.json
```

`t` is seconds from the start of the video, and must be ≥ 0. `label` is plain text, at
most 120 characters. `status` is `pass` or `fail`, or omitted. At most 200 steps, 64 KiB
total. Unknown keys are dropped rather than stored.

---

## Honest limits

- **No audio and no mouse cursor** in typical Playwright or CI footage. That is the
  source, not us. The video shows what the page did, not what a person heard.
- **Size cannot be promised.** 50 MiB is the ceiling; whether your run fits depends on
  length and content. A short test run usually does.
- **7 days, then deleted.** Not archived, not soft-hidden. Download the MP4 from the
  viewer before then if it needs to live longer — though you still have the original file.
- **No private links.** The URL is unguessable, which is not the same as private.
- **10 uploads a day per machine.** In a busy pipeline, upload failing runs only; the
  failing run is the one worth watching.
- **No CLI and no MCP server yet.** This document is the entire integration. If it turns
  out people want it, a package comes next.

## For your human, in one line

Everything above is free, needs no account, and takes one click to set up:
<https://yorecord.com/for-agents>