Surfil

Install

Two commands, entirely in your terminal - no app to open. Install the binary, then link this device. After you link, Surfil connects itself to the coding agents you already use.

Early access. Prebuilt binaries cover macOS (Apple Silicon + Intel), Linux (x64 + arm64) and Windows (x64). Binaries are unsigned for now, so the installer clears the macOS quarantine for you.

1 · Install

On macOS or Linux, run:

curl -fsSL https://surfil.com/install.sh | sh

On Windows, in PowerShell, run:

irm https://surfil.com/install.ps1 | iex

If the installer prints a PATH line, run that line too (once) so your shell can find surfil:

export PATH="$HOME/.local/bin:$PATH"

Run this and approve the code in the browser tab it points you to:

surfil login

The private key is generated on-device and never leaves it - only the public key is registered, and your role in the browser is a single yes/no approval. The moment it links, Surfil auto-detects and connects your installed agents through reversible contracts, so it starts working with them right away.

Agents it connects

On link, Surfil connects every tool it can - each by its real mechanism, never an over-claim. Run surfil doctor to see which you have and how each one connects:

surfil doctor
  • Claude Code - full: base URL (its settings.json env block) + MCP servers.
  • Env-routed CLIs - Codex, opencode, Aider, ShellGPT, mods, llm, Open Interpreter and more honour the standard provider env vars, so the shell profile block routes them.
  • MCP hosts - Cursor, Windsurf, Claude Desktop, Cline: Surfil's MCP server plugs into their config. Their model completions run through their own backend, so their base URL is not redirected here.
  • Detected - Copilot, VS Code, Zed, Gemini CLI, Continue: recognised, with a manual option where the editor allows it (below).

Every change is reversible - each file is snapshotted byte-exact and surfil uninstall restores it. Detection is local and read-only; nothing about which tools you have leaves your machine.

Connect a GUI editor manually

Editors like Cursor and Zed keep their model calls on their own backend, so Surfil cannot redirect them from a config file. Where the editor exposes a custom base-URL setting, point it at the on-device proxy yourself - no CA, no interception of anything else:

surfil connect

It prints the exact clicks per editor and the local endpoint to paste (http://127.0.0.1:8788/v1). For Cursor this covers its chat/plan panel; features that use Cursor's own backend are unchanged.

Build from source

For a platform without a prebuild yet, build it yourself. With Rust installed, run:

cargo build --release -p surfil-cli

Then put the binary on your PATH:

install -m 0755 runtime/target/release/surfil ~/.local/bin/surfil

And link the device the same way:

surfil login

Uninstall

Restores every agent config from its byte-exact snapshot and removes the runtime:

surfil uninstall

Next

  • Quickstart - from install to your first verified receipt.
  • Zero-trace - exactly what leaves the device (and what never does).