---

name: windsurf-multi-env-setup description: | Configure Windsurf across development, staging, and production environments. Use when setting up multi-environment deployments, configuring per-environment secrets, or implementing environment-specific Windsurf configurations. Trigger with phrases like "windsurf environments", "windsurf staging", "windsurf dev prod", "windsurf environment setup", "windsurf config by env". allowed-tools: Read, Write, Edit, Bash(aws:), Bash(gcloud:), Bash(vault:*) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Windsurf Multi-Environment Setup

Overview

Configure Windsurf across development, staging, and production environments.

Prerequisites

• Separate Windsurf accounts or API keys per environment
• Secret management solution (Vault, AWS Secrets Manager, etc.)
• CI/CD pipeline with environment variables
• Environment detection in application

Environment Strategy

Configuration Structure

Copyconfig/
├── windsurf/
│   ├── base.json           # Shared config
│   ├── development.json    # Dev overrides
│   ├── staging.json        # Staging overrides
│   └── production.json     # Prod overrides

base.json

Copy{
  "timeout": 30000,
  "retries": 3,
  "cache": {
    "enabled": true,
    "ttlSeconds": 60
  }
}

development.json

Copy{
  "apiKey": "${WINDSURF_API_KEY}",
  "baseUrl": "https://api-sandbox.windsurf.com",
  "debug": true,
  "cache": {
    "enabled": false
  }
}

staging.json

Copy{
  "apiKey": "${WINDSURF_API_KEY_STAGING}",
  "baseUrl": "https://api-staging.windsurf.com",
  "debug": false
}

production.json

Copy{
  "apiKey": "${WINDSURF_API_KEY_PROD}",
  "baseUrl": "https://api.windsurf.com",
  "debug": false,
  "retries": 5
}

Environment Detection

Copy// src/windsurf/config.ts
import baseConfig from '../../config/windsurf/base.json';

type Environment = 'development' | 'staging' | 'production';

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  const validEnvs: Environment[] = ['development', 'staging', 'production'];
  return validEnvs.includes(env as Environment)
    ? (env as Environment)
    : 'development';
}

export function getWindsurfConfig() {
  const env = detectEnvironment();
  const envConfig = require(`../../config/windsurf/${env}.json`);

  return {
    ...baseConfig,
    ...envConfig,
    environment: env,
  };
}

Secret Management by Environment

Local Development

Copy# .env.local (git-ignored)
WINDSURF_API_KEY=sk_test_dev_***

CI/CD (GitHub Actions)

Copyenv:
  WINDSURF_API_KEY: ${{ secrets.WINDSURF_API_KEY_${{ matrix.environment }} }}

Production (Vault/Secrets Manager)

Copy# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id windsurf/production/api-key

# GCP Secret Manager
gcloud secrets versions access latest --secret=windsurf-api-key

# HashiCorp Vault
vault kv get -field=api_key secret/windsurf/production

Environment Isolation

Copy// Prevent production operations in non-prod
function guardProductionOperation(operation: string): void {
  const config = getWindsurfConfig();

  if (config.environment !== 'production') {
    console.warn(`[windsurf] ${operation} blocked in ${config.environment}`);
    throw new Error(`${operation} only allowed in production`);
  }
}

// Usage
async function deleteAllData() {
  guardProductionOperation('deleteAllData');
  // Dangerous operation here
}

Feature Flags by Environment

Copyconst featureFlags: Record<Environment, Record<string, boolean>> = {
  development: {
    newFeature: true,
    betaApi: true,
  },
  staging: {
    newFeature: true,
    betaApi: false,
  },
  production: {
    newFeature: false,
    betaApi: false,
  },
};

Instructions

Step 1: Create Config Structure

Set up the base and per-environment configuration files.

Step 2: Implement Environment Detection

Add logic to detect and load environment-specific config.

Step 3: Configure Secrets

Store API keys securely using your secret management solution.

Step 4: Add Environment Guards

Implement safeguards for production-only operations.

Output

• Multi-environment config structure
• Environment detection logic
• Secure secret management
• Production safeguards enabled

Error Handling

Examples

Quick Environment Check

Copyconst env = getWindsurfConfig();
console.log(`Running in ${env.environment} with ${env.baseUrl}`);

Resources

• Windsurf Environments Guide
• 12-Factor App Config

Next Steps

For observability setup, see windsurf-observability.