Windsurf Install & Auth
Overview
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.
Prerequisites
- macOS, Windows, or Linux (64-bit)
- 8GB RAM minimum (16GB recommended for large codebases)
- Internet connection for AI features
Instructions
Step 1: Install Windsurf
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
Step 2: Authenticate with Codeium
On first launch, Windsurf prompts for Codeium authentication:
- Click "Sign In" in the welcome tab or Windsurf widget (bottom-right status bar)
- Browser opens to Codeium auth page
- Sign in with Google, GitHub, or email
- Authorization token is stored locally at
~/.codeium/
Verify authentication:
- Check the Windsurf widget in the status bar -- it should show a checkmark
- Open Cascade (Cmd/Ctrl+L) and send a test message
Step 3: Configure for Enterprise / Team
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"
Step 4: Verify AI Features Are Working
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)
Step 5: Select Your AI Model
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 Handling
| 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 |
Examples
Migrate Settings from VS Code
# Windsurf inherits VS Code extensions and settings
# Import on first launch or manually:
# Windsurf > Command Palette > "Import VS Code Settings"
Verify Installation
# Check Windsurf CLI is available
windsurf --version
# Open project in Windsurf from terminal
windsurf /path/to/project
Resources
Next Steps
After authentication, proceed to windsurf-hello-world for your first Cascade interaction.
Source: flight505/skill-forge — distributed by TomeVault.