Surfil

Your first run

The Quickstartgets you to a signed receipt in four commands. This page is the other half: what a healthy first run looks like, and exactly what to check when the receipt doesn't show up.

What success looks like

Surfil measures real traffic, so the input to your first receipt is a normal session with your agent. Nothing about your workflow changes - you invoke Claude Code, Cursor, Codex, or Copilot exactly as before. After one real session:

  • Your agent behaves identically. Interception is byte-exact, so the provider prefix cache keeps working - if your agent got slower or lost cache hits, that is a bug, not expected.
  • surfil mind stats shows facts being written for your sessions.
  • surfil audit produces a signed savings receipt for measured traffic.
  • surfil verify <receipt-id> reports VALID, offline, with no account.

Why the first receipt can take a session or two

A receipt is a measured before/after on your own traffic. Cap needs enough real requests to measure a difference - a single trivial prompt may not recover measurable tokens. Run a normal working session, then surfil audit. Savings are reported in tokens (the fact), as a conservative floor, never as an invented dollar figure.

If nothing appears

  1. Confirm the device is linked. Run surfil doctor. If it shows no device token, run surfil login and approve the code on your Devices page.
  2. Confirm the adapter is wired. surfil doctor lists each detected agent and whether its adapter is active. If an agent is missing, re-run curl -fsSL https://surfil.com/install.sh | sh.
  3. Confirm traffic is flowing through the interceptor. surfil mind statsshould show new facts after a session. No facts means requests are bypassing the single interception point - check that your agent's base URL points at the local runtime.
  4. Then audit. surfil audit measures and signs. If it reports zero recovered tokens, the session was too small to measure - not a failure.
Anything look wrong? surfil uninstall restores every agent config byte-for-byte and leaves zero residue. Nothing here is a one-way door.

What is honest-empty for now

Some dashboard surfaces show a "-" instead of a number. That is deliberate: where a producer isn't built yet (per-seat savings attribution, pooled team credits, device heartbeat last-seen), Surfil shows the absence honestly rather than inventing a value. Those fill in as the producers ship.