Windsurf Integration

AVELIN API is fully compatible with Windsurf — an AI-first IDE by Codeium, built as a fork of VS Code. Windsurf provides intelligent code completion, Cascade (an agentic coding flow), chat assistance, and multi-file editing powered by AVELIN's frontier models.

Why AVELIN + Windsurf? Combine Windsurf's agentic Cascade flows with AVELIN's 1M-token context windows, automatic failover, and competitive per-token pricing — all within a familiar VS Code interface.

Quick Setup

Step 1: Get your AVELIN API key

Sign up at avelin.ai and generate an API key. It will look like sk-ave...xxxx.

Step 2: Install Windsurf

Download and install Windsurf from the official website.

Step 3: Configure Windsurf

1. Open Windsurf
2. Open Settings (gear icon or Cmd+, / Ctrl+,)
3. Navigate to Models
4. Click Add Custom Model (or the + icon)
5. Enter your endpoint configuration:

Recommended: OpenAI-Compatible Endpoint

Alternative: Anthropic Endpoint

Windsurf also supports the Anthropic API format:

We recommend the OpenAI-Compatible endpoint for Windsurf as it provides the broadest feature support in this IDE.

Step 4: Select Your Model

In the Windsurf chat or Cascade panel, click the model dropdown and select your custom AVELIN model. You can switch between models at any time during a session.

Recommended Models

Primary Recommendation: avelin-coding-pro

For everyday coding tasks and Cascade flows:

Alternative Models

Why AVELIN for Windsurf?

1. Cost Optimization

Windsurf sessions — especially Cascade flows — involve many API calls for code generation, file edits, and terminal operations. AVELIN optimizes costs:

• Prompt caching: ~80% cost reduction on repeated system prompts
• Competitive pricing: Lower per-token costs than direct provider APIs
• Pay-per-token: No subscription lock-in or seat limits

2. Model Diversity

Access multiple frontier coding models through one API. AVELIN routes your requests to a diverse set of frontier models across multiple cloud providers, ensuring high availability and consistent quality. If one provider is slow or unavailable, your request automatically routes to the next best option.

3. Reliability

• Automatic failover: If one provider is slow or down, AVELIN switches to another
• Retry logic: Transient errors are handled automatically
• 99.9% uptime: Enterprise-grade infrastructure

4. 1M Context Windows

Windsurf's Cascade flow accumulates context across multiple files and terminal outputs. AVELIN's coding models support 1M tokens — enabling longer agentic sessions without truncation.

Example Workflows

Cascade: Multi-File Feature Implementation

Use Windsurf's Cascade flow to implement a complete feature across multiple files:

Cascade Panel:

You> Add a REST API for user management with CRUD operations,
     input validation, and error handling.

Cascade: I'll implement the user management API. Let me examine
         your project structure first.

[Analyzes project structure]
[Creates models/user.ts]
[Creates validators/user-validator.ts]
[Creates controllers/user-controller.ts]
[Creates routes/user-routes.ts]
[Updates app.ts to register routes]
[Runs tests — all passing]

Done! I've created a complete user management API with:
- User model with validation
- CRUD endpoints (GET, POST, PUT, DELETE)
- Input validation using Zod
- Centralized error handling
- 8 passing tests

Inline Code Completion

Windsurf's autocomplete uses AVELIN for intelligent suggestions:

// You start typing:
async function fetchUserData(userId: string) {

// Windsurf suggests:
async function fetchUserData(userId: string): Promise<User> {
  const user = await prisma.user.findUnique({
    where: { id: userId },
    include: { profile: true, posts: true },
  });
  if (!user) {
    throw new NotFoundError(`User ${userId} not found`);
  }
  return user;
}

Chat-Based Code Review

You: Review @auth-service.ts for security vulnerabilities

Windsurf: Let me analyze the auth service...

[Examines the code]

I found several issues:
1. JWT secret is hardcoded — should use environment variable
2. Token expiration is set to 365 days — too long for access tokens
3. No rate limiting on login endpoint
4. Password reset tokens aren't being invalidated after use

Here are the fixes:
[Provides corrected implementation]

Advanced Configuration

Custom Instructions

Add project-specific instructions in Windsurf Settings > AI > Custom Instructions:

You are working on a Node.js API using Express and TypeScript.
Follow these conventions:
- Use async/await for all async operations
- Include JSDoc comments for all public functions
- Write tests using Vitest
- Use repository pattern for database access
- Always validate inputs with Zod schemas

Model Switching Between Flows

You can use different AVELIN models for different purposes:

• Cascade (agentic flows): avelin-coding-pro — deep reasoning, reliable tool calls
• Inline completions: avelin-fast — low latency for autocomplete
• Chat: avelin-coding-ultra — architectural discussions and reviews

Switch models via the dropdown in each panel independently.

Using with .windsurfrules

Create a .windsurfrules file in your project root to provide persistent context:

# Project Rules

- This is a monorepo using Turborepo
- API services are in packages/api
- Frontend is in packages/web
- All packages use TypeScript strict mode
- Tests use Vitest with @testing-library

Windsurf will include these rules in every request to AVELIN, and prompt caching ensures you're not paying extra for repeated context.

Troubleshooting

Related

• API Quickstart — First API call in 5 minutes
• Cursor Guide — AI-first code editor (VS Code fork)
• Cline Guide — Autonomous coding agent in VS Code
• GitHub Copilot Guide — BYOK integration
• Model Catalog — Full model comparison
• Windsurf Docs — Official Windsurf documentation