leash
Documentation

Leash docs

Everything Leash does, in the order you'll meet it. Reading time: about eight minutes.

Getting started

  • Open the app. No account is needed.
  • Set your rules: allowance, caps, categories and quiet hours. The defaults are sensible.
  • Press Connect PayPal Sandbox and approve on PayPal. If the deployment has no keys, press Start simulated leash instead.
  • Type an errand in plain words, or tap a sample. Watch the agent shop and the leash decide.
  • Approve anything held for you, then refund anything you regret from the ledger.

Simulated vs sandbox

In simulated mode the rules, signed carts, replay protection and ledger work exactly as in sandbox, but PayPal is never called and every ID starts with SIM-. A banner says so on every screen. With PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET set, Leash switches to PayPal Sandbox automatically.

The rules

RuleWhat it doesRange
Monthly allowanceTotal the agent may spend this calendar month (your time zone). Refunds give it back.5–2,000
Max per purchaseThe ceiling for any single line (price × qty).1–200, never above the allowance
Ask me aboveLines above this are held until you tap Approve.0 to the per-purchase cap
Purchases per dayStops runaway loops.1–20
CategoriesOnly these may be bought. Gift cards & cash can never be enabled.8 categories
Quiet hoursNo purchases 00:00–06:00 in your time zone.on / off

Hard limits are clamped on the server (sanitizeRules), so a tampered request can't raise them. Changes apply to the next charge, including carts already planned.

Decision order

Each line gets one of three verdicts. Blocked if any check fails: a never-allowed category, an injected listing, a category that is off, a blocked merchant, the per-purchase cap, the monthly budget, the daily count or quiet hours. Ask if it passes everything but is above your ask line. Otherwise Paid. Lines are evaluated in order, so later lines see the budget the earlier ones would use.

How the agent works

The agent is an LLM routed through Vercel AI Gateway, with fallbacks across providers. It receives your errand, a shortlist of marketplace listings and your rules as context. It returns structured JSON: what it understood, a cart of itemId + quantity + reason, anything it skipped, and a note for you.

  • It can only choose listing IDs that exist. Invented items are dropped.
  • Listing text is written by merchants and treated as untrusted. One demo listing (the lounge pass) contains an injected instruction. The agent sometimes falls for it, and the leash always blocks it.
  • If every model is unreachable, Leash falls back to keyword matching and says so.
  • Progress streams to the page as NDJSON, so you see each step live.

Signed carts

When the agent finishes, the server signs the exact cart with HMAC-SHA256: the lines, a nonce, a tag for your vault and a 15-minute expiry. That token is a cart mandate. To charge, the browser must present the mandate and a line index. The server then:

  • verifies the signature, the vault tag and the expiry;
  • rejects a line that was already spent (409 replay), reserving it before calling PayPal so a double-tap can't double-charge;
  • re-runs every rule against the current server-held ledger;
  • takes the price from the catalog, never from the request.

The client can skip lines but can't add, enlarge or reprice one.

PayPal vault

1  POST /v3/vault/setup-tokens       payment_source.paypal, usage_type MERCHANT
2  payer approves on PayPal          → returns to /api/paypal/complete
3  POST /v3/vault/payment-tokens     setup token → vault_id (stored in your signed session)
4  POST /v2/checkout/orders          intent CAPTURE, payment_source.paypal.vault_id,
                                     stored_credential { MERCHANT, UNSCHEDULED, SUBSEQUENT }
5  POST /v2/checkout/orders/{id}/capture   (only if PayPal returns APPROVED)
6  POST /v2/payments/captures/{id}/refund
7  DELETE /v3/vault/payment-tokens/{id}    when you cut the leash

Every write carries a PayPal-Request-Id derived from the mandate line, so retries are idempotent on PayPal's side too. Leash never sees card numbers or your PayPal password.

Refunds & cutting the leash

Every ledger row has Refund. It issues a full refund on the capture, marks the row and returns the amount to this month's allowance. A row can be refunded once, and the server rejects repeats. Cut the leash deletes the vault token at PayPal and clears the session, so the agent can no longer spend anything.

API reference

RoutePurpose
GET /api/stateMode, rules, usage, ledger
POST /api/paypal/connectStart a leash: returns PayPal's approve URL, or creates a simulated leash
PATCH /api/paypal/connectUpdate rules (clamped server-side)
DELETE /api/paypal/connectCut the leash
POST /api/agent{ errand } → NDJSON stream of steps, then plan with verdicts and mandate
POST /api/paypal/charge{ mandate, line, approve? } → ledger row. 403 blocked, 409 ask/replay, 502 PayPal
POST /api/paypal/refund{ id } → refund ID

Self-hosting

git clone https://github.com/demir-sama/leash && cd leash && npm i
# optional: real sandbox
export PAYPAL_CLIENT_ID=... PAYPAL_CLIENT_SECRET=...
export LEASH_SECRET=$(openssl rand -base64 32)
npm run dev

On Vercel, AI Gateway authenticates over OIDC automatically. Elsewhere, set AI_GATEWAY_API_KEY.

FAQ

Does Leash hold my money?

No. Funds move from your PayPal wallet to the merchant through PayPal. Leash stores only a vault token reference in a signed, http-only cookie.

Can the agent change its own rules?

No. Rules are edited only through the rules panel, clamped on the server, and checked by code the model never touches.

What if a shop tricks the agent?

That's what the leash is for. Injected listings, cash-equivalents and anything over your limits are blocked at plan time and again at charge time.

Which currencies work?

USD, EUR, GBP, CAD, AUD and SGD. All are PayPal-supported, with prices shown in your chosen currency.

Are the shops real?

Not yet. The marketplace is a fictional catalog of 38 listings, so the demo is safe to run. Real merchants would plug in through PayPal Orders the same way.

Where is my data stored?

In your browser only, as a signed cookie. There is no database. Clearing cookies or cutting the leash removes it. See Privacy.