Windsurf is an AI-powered code editor by Codeium (now Cognition AI), built on VS Code. It features Cascade (agentic AI assistant), Supercomplete (intent-aware autocomplete), and deep codebase indexing. Authentication is handled through Codeium accounts, not raw API keys.
macOS:
brew install --cask windsurf
Linux (Debian/Ubuntu):
curl -fsSL https://windsurf.com/install.sh | bash
# Or download .deb from https://windsurf.com/download
Windows: Download installer from https://windsurf.com/download
On first launch, Windsurf prompts for Codeium authentication:
~/.codeium/
Verify authentication:
For team deployments with centralized auth:
// Settings > Windsurf Settings (or ~/.codeium/config.json)
{
"codeium.apiServer": "https://codeium.yourcompany.com",
"codeium.portal.url": "https://portal.yourcompany.com",
"codeium.enterpriseMode": true
}
Enterprise API key (headless / CI environments):
# Set via environment variable for non-interactive use
export CODEIUM_API_KEY="your-enterprise-api-key"
1. Open any project folder in Windsurf
2. Type in a code file -- Supercomplete suggestions should appear
3. Press Cmd/Ctrl+L to open Cascade chat
4. Type "explain this project" -- Cascade should respond with codebase analysis
5. Check status bar widget shows model name (e.g., SWE-1, Claude, GPT)
Cascade supports multiple models. Configure via the model selector dropdown in the Cascade panel:
| Model | Plan Required | Best For |
|---|---|---|
| SWE-1 Lite | Free | Basic coding tasks |
| SWE-1 | Pro ($15/mo) | Complex multi-file edits |
| SWE-1.5 | Pro | Frontier-level performance |
| Claude Sonnet | Pro | Nuanced reasoning |
| GPT-4o | Pro | General-purpose coding |
| Gemini Pro | Pro | Large context tasks |
| Error | Cause | Solution |
|---|---|---|
| "Sign in required" | Auth token expired | Click Windsurf widget > Sign In |
| Cascade not responding | Not authenticated | Check status bar for auth status |
| No completions appearing | Supercomplete disabled | Click status bar widget > enable autocomplete |
| Enterprise auth fails | Wrong API server URL | Verify codeium.apiServer setting |
| "Indexing failed" | Workspace too large | Add .codeiumignore to exclude large dirs |
# Windsurf inherits VS Code extensions and settings
# Import on first launch or manually:
# Windsurf > Command Palette > "Import VS Code Settings"
# Check Windsurf CLI is available
windsurf --version
# Open project in Windsurf from terminal
windsurf /path/to/project
After authentication, proceed to windsurf-hello-world for your first Cascade interaction.