Windsurf IDE Complete Installation Guide: Download, Cascade AI Setup, Custom Models & Git Integration
Windsurf IDE Complete Installation Guide: From Download to Your First AI-Powered Project
Windsurf IDE by Codeium is an AI-native code editor built on a VS Code foundation, featuring Cascade — an agentic AI coding assistant that understands your entire codebase. This guide walks you through every step from installation to launching your first project with full AI and Git integration.
Step 1: Download and Install Windsurf IDE
- Visit the official Windsurf website at
codeium.com/windsurfand click Download for Free. - Select your operating system (Windows, macOS, or Linux).
- Run the installer:
# Windows — run the downloaded .exe installer WindsurfSetup-x.x.x.exe
macOS — move to Applications
mv ~/Downloads/Windsurf.app /Applications/
Linux (Debian/Ubuntu)
sudo dpkg -i windsurf_x.x.x_amd64.deb
sudo apt-get install -f
Linux (Fedora/RHEL)
sudo rpm -i windsurf-x.x.x.x86_64.rpm
- Launch Windsurf IDE. On first launch, you will be prompted to sign in or create a Codeium account.
- Sign up using your email, Google, or GitHub account to activate the free tier.
Step 2: Initial Configuration and Theme Setup
- On first launch, Windsurf offers to import settings from VS Code. Select Import Settings if you are migrating.
- Choose your preferred color theme and keymap bindings.
- Open Settings with
Ctrl+,(Windows/Linux) orCmd+,(macOS) to customize editor preferences:
// settings.json recommended baseline
{
"editor.fontSize": 14,
"editor.minimap.enabled": false,
"editor.formatOnSave": true,
"editor.tabSize": 2,
"windsurf.cascade.autoContext": true
}Step 3: Activate and Configure Cascade AI Assistant
Cascade is Windsurf's flagship AI feature. It operates in two modes: **Write mode** (code generation and editing) and **Chat mode** (Q&A and codebase exploration).
-
Open the Cascade panel by pressing
Ctrl+L(orCmd+Lon macOS), or click the Cascade icon in the sidebar. -
Verify your account is connected — you should see your username at the bottom of the panel.
-
Test Cascade by typing a prompt:
Create a REST API with Express.js that has CRUD endpoints for a todo list with input validation -
Cascade will analyze your workspace, generate files, and offer to apply changes. Click Accept All to apply.
Cascade Modes Explained
| Mode | Shortcut | Best For |
|---|---|---|
| Write Mode | Ctrl+L / Cmd+L | Multi-file code generation, refactoring, creating new features |
| Chat Mode | Ctrl+L then toggle | Asking questions about codebase, debugging, explanations |
| Inline Edit | Ctrl+I / Cmd+I | Quick edits within the current file, targeted changes |
| Autocomplete | Tab to accept | Real-time code suggestions as you type |
Step 4: Select and Configure Custom AI Models
Windsurf supports multiple AI models. You can switch models based on task complexity.
-
Open the Cascade panel and click the model selector dropdown at the top.
-
Available models include GPT-4o, Claude Sonnet, Claude Opus, and Codeium’s own models. Pro and Ultimate tier users unlock premium models.
-
For API-based custom model configuration, navigate to Settings > Windsurf > Model Configuration:
// Custom model provider configuration { “windsurf.modelProvider”: “custom”, “windsurf.customEndpoint”: “https://api.your-provider.com/v1”, “windsurf.customApiKey”: “YOUR_API_KEY”, “windsurf.customModelId”: “your-model-name” } -
Test the connection by sending a simple prompt to Cascade after saving.
Step 5: Git Integration Setup
Windsurf inherits VS Code's Git integration and adds AI-enhanced commit workflows.
- Ensure Git is installed on your system:
git —version
If not installed:
Windows: winget install Git.Git
macOS: brew install git
Linux: sudo apt install git
- Configure your Git identity:
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"- Initialize a repository or clone an existing one:
# New project
mkdir my-project && cd my-project
git init
# Clone existing
git clone https://github.com/your-username/your-repo.git
cd your-repo- Open the project in Windsurf:
windsurf .- Use the Source Control panel (
Ctrl+Shift+G) to stage, commit, and push. Cascade can auto-generate commit messages — click the sparkle icon in the commit message box.
Step 6: Start Your First Project
- Create a new project directory and open it in Windsurf.
- Open Cascade (
Ctrl+L) and describe what you want to build:
Scaffold a Next.js 14 project with TypeScript, Tailwind CSS, and a landing page component with a hero section and feature grid- Review the proposed changes in the diff view. Cascade shows exactly what files will be created or modified.
- Accept the changes and run the development server:
npm install
npm run dev- Continue iterating by giving Cascade follow-up instructions to refine your code.
Pro Tips for Power Users
- Context Pinning: Use
@fileor@foldermentions in Cascade prompts to direct the AI’s attention to specific parts of your codebase:@src/utils/auth.ts refactor this to use JWT tokens. - Terminal Integration: Cascade can read terminal output. If a build fails, paste the error or ask Cascade to check the terminal for errors.
- Multi-file Awareness: Cascade indexes your entire workspace. Ask broad questions like “Where is the user authentication logic and how does it connect to the database?”
- Keyboard Shortcut Mastery: Press
Ctrl+Shift+Pand type Windsurf to see all available AI commands. - Extension Compatibility: Most VS Code extensions work in Windsurf. Install them via the Extensions panel (
Ctrl+Shift+X). - Memory and Rules: Create a
.windsurfrulesfile in your project root to define persistent instructions for Cascade, such as coding style or framework preferences.
Troubleshooting Common Issues
| Issue | Cause | Solution |
|---|---|---|
| Cascade not responding | Authentication expired or network issue | Sign out and sign back in. Check your internet connection. Restart Windsurf. |
| Autocomplete not appearing | Extension conflict or disabled setting | Disable competing AI extensions (Copilot, Tabnine). Check windsurf.autocomplete.enabled is true. |
| Git not detected | Git not in system PATH | Run git --version in the integrated terminal. If missing, install Git and restart Windsurf. |
| High memory usage | Large workspace indexing | Add large folders (e.g., node_modules, .git) to .windsurfignore or settings exclude patterns. |
| Custom model connection failure | Incorrect API key or endpoint | Verify the endpoint URL ends with /v1. Double-check the API key. Test the endpoint with curl. |
Frequently Asked Questions
Is Windsurf IDE free to use, and what are the plan differences?
Yes, Windsurf offers a free tier that includes Cascade AI with limited premium model credits, autocomplete, and full editor functionality. The Pro plan adds more credits and access to advanced models like Claude Opus and GPT-4o. The Ultimate plan provides unlimited flows and priority access to the latest models. All plans include Git integration, extension support, and the full editor experience.
Can I use Windsurf with existing VS Code extensions and settings?
Windsurf is built on the VS Code foundation and supports the vast majority of VS Code extensions. On first launch, you can import your existing VS Code settings, keybindings, and extensions. Some AI-specific extensions like GitHub Copilot may conflict with Cascade — it is recommended to disable competing AI autocomplete extensions to avoid duplicate suggestions.
How does Cascade differ from regular AI code assistants like Copilot?
Cascade is an agentic AI assistant, meaning it can autonomously perform multi-step tasks across multiple files. Unlike traditional autocomplete-based assistants, Cascade can read your entire codebase, create and modify multiple files in a single operation, run terminal commands, and maintain context across a conversation. It operates more like an AI pair programmer than a suggestion engine.