# Windsurf Integration

AVELIN API is fully compatible with [Windsurf](https://windsurf.com) — 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](https://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](https://windsurf.com/downloads).

### 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

| Field | Value |
|---|---|
| **Provider** | OpenAI Compatible |
| **Base URL** | `https://api.avelin.ai/v1` |
| **API Key** | `sk-ave...xxxx` |
| **Model ID** | `avelin-coding-pro` |

#### Alternative: Anthropic Endpoint

Windsurf also supports the Anthropic API format:

| Field | Value |
|---|---|
| **Provider** | Anthropic |
| **Base URL** | `https://api.avelin.ai` |
| **API Key** | `sk-ave...xxxx` |
| **Model ID** | `avelin-coding-pro` |

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:

| Feature | avelin-coding-pro | Why it matters for Windsurf |
|---|---|---|
| **Context window** | **1M tokens** | Large codebases and multi-file Cascade flows without context loss |
| **Max output** | **65K tokens** | Generate large code files and comprehensive implementations |
| **Throughput** | **~100 tokens/sec** | 2× faster than standard tiers — responsive Cascade interactions |
| **Reasoning** | Deep step-by-step thinking | Catches subtle bugs, understands architectural impact |
| **Tool calling** | First-class support | Reliable file editing and terminal operations in Cascade |

### Alternative Models

| Model | When to use |
|---|---|
| `avelin-coding-fast` | Lighter coding tasks, quick questions — saves cost on simple work |
| `avelin-coding-ultra` | System design, architecture reviews, security-sensitive refactors |
| `avelin-fast` | Inline completions and simple lookups — lowest cost, fastest response |

---

## 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:

```typescript
// 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:

```markdown
# 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

| Issue | Solution |
|---|---|
| **"Model not found"** | Ensure the Model ID matches exactly (e.g., `avelin-coding-pro`) |
| **"API key invalid"** | Verify your AVELIN API key starts with `sk-ave` and has not been revoked |
| **Slow completions** | Switch to `avelin-fast` for inline completions; use `avelin-coding-pro` for chat/Cascade |
| **Cascade tool calls failing** | Use `avelin-coding-pro` — it has first-class function calling support |
| **Context too long errors** | Start a new Cascade flow to reset context, or exclude files from the workspace index |
| **Connection timeout** | Check that your base URL is correct: `https://api.avelin.ai/v1` (OpenAI) or `https://api.avelin.ai` (Anthropic) |
| **Streaming not working** | Use the OpenAI-Compatible endpoint for best streaming support in Windsurf |

---

## Related

- [API Quickstart](../../api/quickstart.md) — First API call in 5 minutes
- [Cursor Guide](cursor.md) — AI-first code editor (VS Code fork)
- [Cline Guide](cline.md) — Autonomous coding agent in VS Code
- [GitHub Copilot Guide](github-copilot.md) — BYOK integration
- [Model Catalog](../../models/README.md) — Full model comparison
- [Windsurf Docs](https://docs.windsurf.com) — Official Windsurf documentation