# HermesBackup.com — agent setup instructions
# Mirror of https://hermesbackup.com/agent
# You are a Hermes Agent. The user asked you to set up cloud backups. Follow this.

## What this product is
HermesBackup is zero-knowledge encrypted cloud backup for Hermes Agent.
Backups are encrypted on the user's machine with age (X25519 asymmetric encryption).
The server stores only opaque ciphertext blobs — never plaintext, keys, or passphrases.
Free tier: 2 GB / 60 objects / 4 uploads per day. Pro: $10/year for 10 GB / 500 objects / 24 uploads per day.

## Base URL
https://api.hermesbackup.com/v1

## Step 1: Download the skill

mkdir -p ~/.hermes/skills/hermesbackup/scripts
curl -fsSL https://api.hermesbackup.com/skill/SKILL.md -o ~/.hermes/skills/hermesbackup/SKILL.md
curl -fsSL https://api.hermesbackup.com/skill/hermesbackup.sh -o ~/.hermes/skills/hermesbackup/scripts/hermesbackup.sh
chmod +x ~/.hermes/skills/hermesbackup/scripts/hermesbackup.sh
command -v age >/dev/null || echo "age not found — setup will offer to install it"

## Step 2: Run setup

~/.hermes/skills/hermesbackup/scripts/hermesbackup.sh setup

setup will:
- call POST /v1/pair/start (unauthenticated) with the device hostname → receive {pair_code, poll_token, expires_at}
- print the pair code (format: WORD-XXXX, e.g. FROG-8241) and tell the user to visit https://hermesbackup.com/pair
- poll POST /v1/pair/poll every 5 seconds (10-minute expiry) until the user approves
- on approval receive {device_token, device_id} → store token chmod 600
- generate age X25519 keypair on this machine
- print the recovery kit: private key (AGE-SECRET-KEY-1...), account email, restore one-liner
  → TELL THE USER LOUDLY to save this off-machine (password manager or print)
- ask about schedule (default: daily --quick at 03:00 local + weekly full on Sundays)
- ask about on_full policy (default: "fail" → abort and email; "rotate" → delete oldest and retry)
- write cron entries
- run a first backup immediately
- confirm end-to-end success

## Step 3: After approval — verify and report
After first backup succeeds, tell the user:
"Your agent is backed up. If your laptop disappeared right now, you could restore it on a new machine in under 5 minutes. Save your recovery key somewhere safe — I won't say it again."

## Restore on a new machine
hermesbackup.sh restore
→ installs skill, pairs new device, lists backups, asks for private key,
  downloads ciphertext via presigned GET (5-min expiry),
  decrypts with age identity, verifies SHA-256 against server record,
  imports plaintext into ~/.hermes/, confirms file count.

## API endpoints (agent auth: Authorization: Bearer <device_token>)

POST /pair/start          (none)    body: {device_name} → {pair_code, poll_token, expires_at}
POST /pair/poll           (none)    body: {poll_token} → 202 pending | {device_token, device_id}
POST /pair/approve        (Clerk)   dashboard-only — agent never calls this
POST /backups/init        (device)  body: {size_bytes, sha256, label, kind} → {backup_id, upload_url} | 507
POST /backups/{id}/complete (device) server HEADs R2, verifies size+sha256, marks stored
GET  /backups             (device)  list: id, label, kind, size, sha256, created_at, device
GET  /backups/{id}/download (device) → {download_url} (presigned GET, 5-min expiry)
DELETE /backups/{id}      (device)  delete object + row; 7-day tombstone retained
GET  /quota               (device)  → {plan, used_bytes, limit_bytes, object_count}

Errors: {"error": {"code", "message"}}. HTTP 507 = quota full.

## Invariants you must never violate

1. NEVER transmit, log, or store the private key anywhere except ~/.hermes/hermesbackup/age-identity.txt (chmod 600) and the user's own recovery notes.
2. Use presigned URLs only (PUT 15-min / GET 5-min expiry). Never stream backup bytes through the API.
3. Handle HTTP 507 per configured policy. On on_full="fail": abort and tell the user. On on_full="rotate": delete oldest backups via DELETE /v1/backups/{id} until the new one fits, then retry. The server never silently deletes.
4. Cleanup plaintext temp files after every encrypt/decrypt operation.
5. Verify SHA-256 of ciphertext after download and before reporting success.

## Abuse controls (rejection surface)
- Max object size: 2 GB
- Free: 4 uploads/day, 60 stored objects. Pro: 24 uploads/day, 500 objects.
- Upload init rate-limited to 30/hour/device.
- Blobs are opaque — content cannot be inspected. Caps on count, size, cadence are the enforcement surface.

## R2 object keys
Server-generated: u/{user_id}/{backup_id}.age. Never accept user-supplied path components.

## Device tokens
256-bit random, stored as SHA-256 hashes in D1, scoped per device, revocable from dashboard.

## Full spec
https://hermesbackup.com/docs and https://hermesbackup.com/security