@kentcdodds/agent-files

@kentcdodds/agent-files

Intent

Move file bytes between an agent's own machine (Cursor cloud agent VM, local shell, another process) and Kody runtimes — in either direction — without shoving multi‑MB payloads through MCP base64 or Dropbox. Mint a short‑lived R2 PUT URL with a small MCP/execute call, PUT the bytes with curl/fetch from the machine that has them, then read the public managed *.r2.dev downloadUrl from Kody (or hand it to another agent). Objects live in the agent-files bucket on Kent's Cloudflare account and expire after about a week.

When to use

• A cloud agent VM (or any host without Cloudflare credentials) needs to stage bytes that Kody will later fetch or copy into another R2 bucket.
• Kody needs to publish a download URL that a machine without secrets can GET.
• Agent-to-agent handoffs of images, archives, logs, or other binaries.

Prefer this over MCP bytesBase64 for anything beyond a few hundred KB.

Prerequisites

• User secret cloudflareApiToken (same token used by home-maintenance / stash) with permission to manage R2 on Cloudflare account a41d50ecaf0ae0f86dd1824ef6729cb2.
• Token must be able to call https://api.cloudflare.com (R2 bucket create, managed public domain, temp-access-credentials).

Create or rotate the token in the Cloudflare dashboard: API Tokens. Prefer a custom token with Account → Cloudflare R2 → Edit (and Tokens → Read for parent key id resolution).

Setup

1. Ensure cloudflareApiToken exists as a user secret in Kody (name only — never paste the value into chat or commits).
2. First successful create-upload / upload auto-ensures:
   • R2 bucket agent-files on account a41d50ecaf0ae0f86dd1824ef6729cb2
   • Managed public *.r2.dev domain
   • Object lifecycle delete after ~7 days (best-effort; see below if it fails)
3. No package-local secrets beyond the mounted user token.

Manual lifecycle (if auto-apply fails)

Dashboard → R2 → bucket agent-files → Settings → Object lifecycle → add a rule that deletes objects after 7 days (empty prefix = whole bucket).

How it works

1. Call ./create-upload with { filename, confirm: true } (optional contentType, prefix, expiresInSeconds).
2. PUT file bytes to upload.url with the returned upload.headers (Content-Type must match) — typically from the VM/machine that has the file.
3. From Kody execute (or another package), fetch(downloadUrl) to read the bytes, or pass downloadUrl into something like @kentcdodds/cloudflare/r2-put-object to copy into a durable R2 bucket.
4. Optionally ./get / ./delete by key.

Handoffs are short-lived: upload URL TTL ~1h (default); objects ~7 day lifecycle.

Prefer ./create-upload over ./upload. The latter accepts small bytesBase64 payloads only and rejects oversized MCP bodies.

Done when

• create-upload with confirm: true returns upload.url + downloadUrl
• A real PUT to upload.url succeeds
• GET downloadUrl returns 200 with the bytes
• ./get({ key }) reports found: true
• ./delete({ key, confirm: true }) removes the object

Bucket / public URL base are created on first use; check the first create-upload result's downloadUrl host (e.g. https://pub-….r2.dev/…).