Beginner12 min1 prerequisite

Install Windsurf, configure your workspace, and customize the editor for optimal AI development.

Setting Up Windsurf

This lesson walks through installing Windsurf, creating an account, and configuring the editor for your workflow.

System Requirements

Minimum Requirements

macOS: 10.15 Catalina or later
Windows: 10 or later
Linux: Ubuntu 18.04+, Debian 10+, Fedora 32+
RAM: 4GB minimum, 8GB recommended
Storage: 500MB for installation

Recommended Setup

Modern multi-core processor
16GB RAM for large projects
SSD for faster indexing
Stable internet connection

Installation

macOS

Option 1: Direct Download

Visit codeium.com/windsurf
Download the macOS installer
Open the .dmg file
Drag Windsurf to Applications
Launch from Applications

Option 2: Homebrew

Terminal

brew install --cask windsurf

Windows

Visit codeium.com/windsurf
Download the Windows installer
Run the .exe installer
Follow installation prompts
Launch Windsurf from Start menu

Linux

Debian/Ubuntu:

Terminal

# Download .deb package from website, then:
sudo dpkg -i windsurf_*.deb
sudo apt-get install -f  # Install dependencies

Fedora/RHEL:

Terminal

# Download .rpm package from website, then:
sudo rpm -i windsurf_*.rpm

AppImage (Universal):

Terminal

chmod +x Windsurf_*.AppImage
./Windsurf_*.AppImage

Creating an Account

Sign Up

Launch Windsurf
Click "Sign Up" on the welcome screen
Choose authentication method:
- Email and password
- Google account
- GitHub account

Verify Email

If using email signup:

Check your inbox
Click verification link
Return to Windsurf

Free Tier Activation

Your account automatically includes:

Unlimited Supercomplete
Daily Cascade credits
Basic Flows

Initial Configuration

First Launch

When you first open Windsurf:

Terminal

┌─────────────────────────────────────────────────────────┐
│              Welcome to Windsurf                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Let's personalize your experience                      │
│                                                         │
│  1. Choose color theme                                  │
│  2. Select keybindings (VS Code, Vim, Emacs)           │
│  3. Import settings from VS Code (optional)            │
│  4. Configure AI preferences                            │
│                                                         │
│                    [Get Started]                        │
└─────────────────────────────────────────────────────────┘

Import VS Code Settings

If migrating from VS Code:

Click "Import Settings"
Select what to import:
- Extensions
- Keybindings
- Settings
- Snippets

Windsurf handles the migration automatically.

Workspace Setup

Opening a Project

Terminal

File → Open Folder → Select your project

Or via terminal:

Terminal

windsurf /path/to/your/project

Trust Prompt

For new workspaces:

Terminal

┌─────────────────────────────────────────────────────────┐
│  Do you trust the authors of this folder?               │
│                                                         │
│  [Trust Folder] [Trust Folder & Enable All Features]    │
└─────────────────────────────────────────────────────────┘

Choose "Trust Folder & Enable All Features" for full AI capabilities.

Workspace Indexing

Windsurf indexes your project for AI context:

Terminal

Indexing workspace...
├── Scanning files
├── Building code graph
├── Creating embeddings
└── Ready for AI features

Status bar: "AI Ready ✓"

Large projects may take a few minutes on first open.

Essential Settings

AI Configuration

Open Settings (Cmd/Ctrl+,) and search:

Terminal

{
  // Supercomplete settings
  "codeium.enableAutoCompletions": true,
  "codeium.completionDelay": 150,

  // Cascade settings
  "cascade.autoContext": true,
  "cascade.includeDependencies": true,

  // General AI settings
  "windsurf.telemetry.enabled": true,
  "windsurf.ai.maxContextFiles": 20
}

Editor Preferences

Common customizations:

Terminal

{
  // Editor behavior
  "editor.formatOnSave": true,
  "editor.fontSize": 14,
  "editor.tabSize": 2,

  // Theme
  "workbench.colorTheme": "Windsurf Dark",

  // Files
  "files.autoSave": "onFocusChange",
  "files.exclude": {
    "**/node_modules": true,
    "**/.git": true
  }
}

Keybindings

Key Windsurf shortcuts:

Action	macOS	Windows/Linux
Open Cascade	`Cmd+L`	`Ctrl+L`
Supercomplete	Auto	Auto
Accept completion	`Tab`	`Tab`
Inline AI	`Cmd+I`	`Ctrl+I`
Command palette	`Cmd+Shift+P`	`Ctrl+Shift+P`

Custom Keybindings

Add to keybindings.json:

Terminal

[
  {
    "key": "cmd+shift+l",
    "command": "cascade.newChat"
  },
  {
    "key": "cmd+shift+k",
    "command": "cascade.clearChat"
  }
]

Extension Management

VS Code Extension Compatibility

Most VS Code extensions work in Windsurf:

Terminal

Cmd/Ctrl+Shift+X → Extensions view

Search and install as normal.

Recommended Extensions

Language Support:

Python
ESLint
Prettier

Development:

GitLens
Docker
Thunder Client

Productivity:

Todo Tree
Path Intellisense

Extension Conflicts

If AI features conflict with other extensions:

Disable conflicting completions
Check for duplicate functionality
Give priority to Windsurf AI

Example: Disable GitHub Copilot if installed:

Terminal

{
  "github.copilot.enable": false
}

Project-Specific Configuration

Workspace Settings

Create .windsurf/settings.json:

Terminal

{
  "cascade.alwaysInclude": [
    "README.md",
    "package.json",
    "tsconfig.json"
  ],
  "cascade.exclude": [
    "node_modules",
    "dist",
    ".git"
  ],
  "supercomplete.language": "typescript"
}

AI Instructions

Create .windsurf/instructions.md:

Terminal

# Project Context

This is a Next.js 16 e-commerce application.

## Tech Stack
- Next.js 16 (App Router)
- TypeScript
- Tailwind CSS v4
- Prisma with PostgreSQL

## Conventions
- Use Server Components by default
- API routes in /app/api
- Components in /components
- Utilities in /lib
- Dynamic params are async (await params)

## Important Notes
- Prices are stored in cents
- All dates are UTC
- Use Zod for validation

Cascade will read this for context.

Model Preferences

Configure preferred models in .windsurf/settings.json:

Terminal

{
  "cascade.preferredModel": "claude-4.6-sonnet",
  "cascade.fallbackModel": "claude-4.6-haiku",
  "supercomplete.model": "fast"
}

Account Management

Viewing Usage

Check your AI usage:

Click profile icon (bottom-left)
Select "Usage & Billing"
View Cascade credits remaining

Upgrading to Pro

If you need more credits:

Profile → Upgrade
Choose plan
Enter payment details
Immediate activation

Team Setup

For team accounts:

Admin creates organization
Invites team members
Configures shared settings
Assigns seats

Troubleshooting

AI Features Not Working

Terminal

1. Check login status (profile icon)
2. Verify internet connection
3. Reload window (Cmd+Shift+P → "Reload Window")
4. Check status bar for errors

Slow Indexing

Terminal

For large projects:
1. Exclude unnecessary directories
2. Increase available RAM
3. Use SSD storage
4. Wait for initial index to complete

Extension Issues

Terminal

If extensions misbehave:
1. Disable recently added extensions
2. Check for updates
3. Review extension compatibility
4. Report to extension author

Summary

Download from codeium.com/windsurf
Create account with email or OAuth
Import VS Code settings if migrating
Configure AI settings and keybindings
Set up workspace with .windsurf directory
Install extensions as needed

Next Steps

With Windsurf configured, let's dive into Cascade—the powerful AI assistant at the heart of the Windsurf experience.

Mark this lesson as complete to track your progress