Windsurf IDE with the Gateway

Windsurf is Codeium's AI-powered code editor featuring Cascade, an agentic AI assistant. You can route Windsurf's custom model traffic through the Keeptrusts gateway to enforce governance policies, audit interactions, and control costs.

Use this page when

• You are working through Windsurf IDE with the Gateway as an implementation or operating workflow in Keeptrusts.
• You need the practical steps, expected outcomes, and related validation guidance in one place.
• If you need exact field-by-field reference instead of a workflow page, use the linked reference pages in Next steps.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Prerequisites

Before you begin, ensure you have:

• Windsurf installed (latest version)
• The kt CLI installed and configured
• The gateway running with kt gateway run
• An access key or provider API key

Start the gateway:

kt gateway run --policy-config policy-config.yaml

How Windsurf's AI Features Work

Windsurf provides several AI capabilities:

• Cascade — an agentic AI chat that can browse files, run commands, and make multi-file edits
• Autocomplete — inline code completions as you type
• Supercomplete — enhanced completions that predict your next action
• Command — inline code generation via Cmd-K / Ctrl-K

Windsurf uses its own Codeium-hosted models for autocomplete and Supercomplete. Cascade and Command features support custom model endpoints.

Configure Custom Model Endpoint

1. Open Windsurf.
2. Open Settings (press Cmd+, or Ctrl+,).
3. Search for "model" or navigate to the AI model configuration section.
4. Under Custom API Providers, add a new provider:
   • Provider Name: Keeptrusts Gateway
   • Base URL: http://localhost:41002/v1
   • API Key: Your Keeptrusts access key
5. Select the models available through your gateway (e.g., gpt-4o, claude-sonnet-4-20250514).
6. Set the custom provider as the active model for Cascade and Command.

Which Features Route Through the Gateway

Feature	Routes Through Gateway	Notes
Cascade chat	Yes	When using a custom model provider
Command (Cmd-K)	Yes	When using a custom model provider
Autocomplete	No	Uses Codeium's built-in models
Supercomplete	No	Uses Codeium's built-in infrastructure

Windsurf's autocomplete and Supercomplete features use Codeium's proprietary model infrastructure and do not support custom endpoints. Cascade and Command features route through the gateway when configured with a custom provider.

Verify Traffic Flows Through the Gateway

After configuring the custom model provider, open the Cascade panel and send a message. Then verify:

kt events tail

You see events showing the request, model used, token count, and policy evaluation result. Each Cascade interaction generates at least one event in the gateway log.

Cascade and Gateway Policies

Cascade is an agentic assistant that can:

• Read and write files in your project
• Run terminal commands
• Browse multiple files for context
• Make multi-file edits in a single interaction

When Cascade routes through the gateway:

• Redaction policies scrub secrets and sensitive data from file contents before they reach the provider.
• Blocking policies can prevent certain types of requests (e.g., requests containing production credentials).
• Cost attribution tracks the typically higher token usage of agentic interactions.
• Audit logging records the full conversation including tool-use steps.

Example Policy for Windsurf

A policy configuration optimized for Windsurf's agentic workflows:

pack:
  name: windsurf-rules-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - safety-filter
policy:
  safety-filter:
    block_if:
    - (?i)(api[_-]?key|secret|password|token)\s*[=:]\s*['"][^'"]+['"]
    - '(?i)(AWS_ACCESS_KEY|AWS_SECRET_KEY)\s*=\s*\S+'
    action: block

Working with Cascade's Context Window

Cascade sends large amounts of context (file contents, terminal output, project structure) to the model. Keep these considerations in mind:

• Large context requests consume more tokens — monitor usage with kt events tail.
• Your gateway's token limit policies apply to Cascade's full context payload.
• If a policy blocks a request for exceeding token limits, Cascade may retry with reduced context.

Troubleshooting

Cascade shows "connection error"

• Verify the gateway is running: kt gateway status
• Confirm the Base URL is http://localhost:41002/v1.
• Check that port 41002 is accessible.
• Review kt logs for connection errors.

Custom model not appearing in model selector

• Ensure you added the provider correctly in settings.
• Restart Windsurf after adding a new provider.
• Verify the gateway responds to model list requests: curl http://localhost:41002/v1/models

Autocomplete not governed

Windsurf's autocomplete uses Codeium's built-in models and cannot be routed through a custom endpoint. If you need governance over all completions, consider:

• Using Cascade and Command for governed interactions.
• Relying on your organization's network-level controls for Codeium traffic.

High token usage from Cascade

Cascade's agentic workflow can consume many tokens per interaction. To manage costs:

• Set token limits in your policy configuration.
• Use kt events tail to monitor per-interaction token counts.
• Configure cost attribution to track usage by developer.

Privacy and Compliance

When Windsurf traffic routes through the gateway:

• File contents sent as context are subject to your redaction policies.
• All interactions are logged for compliance and audit purposes.
• You maintain organizational control over what data reaches the upstream provider.
• Cost records provide accountability for AI usage.

For AI systems

• Canonical terms: Keeptrusts, Windsurf IDE with the Gateway, ide-integration.
• Exact feature, config, command, or page names: Windsurf IDE with the Gateway.
• Use the linked audience and reference pages in Next steps when you need deeper source material.

For engineers

• Use the commands, configuration examples, API payloads, or UI steps in this page as the working baseline for Windsurf IDE with the Gateway.
• Validate the result with the expected outcomes, troubleshooting notes, or linked workflow pages in this page and Next steps.

For leaders

• This page matters when planning rollout, governance, support ownership, or operating decisions for Windsurf IDE with the Gateway.
• Use the linked audience, architecture, and workflow pages in Next steps to connect this detail to broader implementation choices.

Next steps

• Configure policies for your team's Windsurf usage.
• View events to audit Cascade conversations.
• Configure access keys for team authentication.