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 auto-loads the repository’s canonical AGENTS.md as project context. Keep reusable, task-specific guidance in the shared skills instead of copying the same always-on instructions into a Windsurf-only root file.

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