Windsurf + fak Integration Guide

This guide shows how to put fak in front of Windsurf’s Cascade agent. Every tool call Cascade proposes is adjudicated by the kernel before it runs: dangerous calls are denied by structure, malformed calls are repaired, and untrusted tool results are quarantined before they reach the model’s context.

Windsurf project context for this repo lives in .windsurfrules (auto-loaded), which points back here.

How it fits

Windsurf (Cascade)  ──▶  fak serve (gateway)  ──▶  your model (cloud or local)
        ▲                  adjudicates every            │
        └────── results ───  tool call ◀────────────────┘

The gateway speaks an OpenAI-compatible API, so any Windsurf “custom / BYOK OpenAI-compatible” model setting can point at it.

Prerequisites

# Build fak (the Go module is the repo root)
git clone https://github.com/anthony-chaudhary/fak && cd fak
go build -o fak ./cmd/fak
./fak version

Quick start: put the kernel in front of Cascade

# Start the gateway with a read-only capability floor (no key needed to try it)
./fak serve \
  --addr 127.0.0.1:8080 \
  --provider openai \
  --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b \
  --policy examples/customer-support-readonly-policy.json

Then in Windsurf, set the model provider to an OpenAI-compatible endpoint with base URL http://127.0.0.1:8080/v1 and any non-empty API key (e.g. fak-local). Cascade’s edits and commands now flow through the capability floor.

Verify the gateway is healthy:

curl http://127.0.0.1:8080/healthz

Author a capability floor

Reproduce a denial offline before trusting it in the IDE:

./fak preflight \
  --tool run_command \
  --args '{"command":"rm -rf /tmp"}' \
  --policy examples/customer-support-readonly-policy.json
# verdict=DENY reason=POLICY_BLOCK

Start a custom policy from the built-in default and validate it:

./fak policy --dump > windsurf-policy.json
./fak policy --check windsurf-policy.json

Cross-references

License

Apache-2.0