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.

windsurf-install-auth

快捷安装