@viudes/windsurf-api 0.1.3

package/.env.example

@@ -0,0 +1,148 @@
+# ========== Server ==========
+PORT=3003
+# API key for incoming requests (leave empty for open access)
+API_KEY=
+# Directory for persisted JSON state and logs.
+# Default: ~/.windsurf-api (a hidden per-user folder; cross-platform). Docker deployments should use /data.
+DATA_DIR=
+
+# In-memory duplicate response cache. Max bytes accepts b/k/kb/kib/m/mb/mib/g/gb/gib.
+# RESPONSE_CACHE_ENABLED=1
+# RESPONSE_CACHE_MAX_BYTES=16m
+
+# ========== Codeium Auth ==========
+# Option 1: Direct API key from Windsurf
+CODEIUM_API_KEY=
+
+# Option 2: Token from windsurf.com/show-auth-token
+CODEIUM_AUTH_TOKEN=
+
+# ========== Language Server ==========
+# Path to the language server binary.
+# Linux x64 default: /opt/windsurf/language_server_linux_x64
+# Linux arm64 default: /opt/windsurf/language_server_linux_arm
+# macOS Apple Silicon default: ~/.windsurf/language_server_macos_arm
+# macOS Intel default: ~/.windsurf/language_server_macos_x64
+LS_BINARY_PATH=/opt/windsurf/language_server_linux_x64
+# Per-proxy language server data root.
+# macOS local runs should use a user-writable directory, e.g. ~/.windsurf/data.
+LS_DATA_DIR=/opt/windsurf/data
+# gRPC port for language server
+LS_PORT=42100
+# Max live LS instances. Empty = memory-aware default (about 700MB per LS).
+# Set low on small VPSes, especially when using per-proxy/per-user LS isolation.
+# LS_MAX_INSTANCES=2
+# Prewarm the no-proxy default LS on startup. Set 0 on low-memory hosts when
+# all real traffic uses per-account proxies; LS will start lazily on demand.
+# LS_PREWARM_DEFAULT=1
+# How long a request waits for an active non-default LS to go idle before
+# returning LS_POOL_EXHAUSTED / LS_MEMORY_GUARD.
+# LS_POOL_WAIT_MS=30000
+# Minimum available memory required before spawning another non-default LS. If
+# unset, WindsurfAPI uses observed live LS RSS + margin after the first LS is
+# ready, falling back to 700MB before any sample exists. Set this to pin a
+# fixed operator budget. Accepts 700m / 1g / bytes.
+# LS_SPAWN_MIN_AVAILABLE_BYTES=700m
+# Dynamic RSS estimate floor/margin used only when LS_SPAWN_MIN_AVAILABLE_BYTES
+# is unset.
+# LS_OBSERVED_RSS_MIN_BYTES=384m
+# LS_OBSERVED_RSS_MARGIN_PERCENT=35
+# Disable memory guard only on hosts with external memory control/monitoring.
+# LS_MEMORY_GUARD=1
+# Stop idle non-default LS instances after this many milliseconds. 0 disables.
+# LS_IDLE_TTL_MS=1200000
+# Idle reaper interval. Empty = derived from LS_IDLE_TTL_MS.
+# LS_IDLE_SWEEP_MS=300000
+# Prewarm every configured proxy LS on startup. Default off to avoid memory spikes.
+# LS_PREWARM_PROXIES=0
+# Also prewarm/probe LS when adding accounts from Dashboard/batch/OAuth.
+# Default off so bulk account import cannot spawn many heavy LSPs at once.
+# LS_PREWARM_ON_ACCOUNT_ADD=0
+# Background credit/token refresh skips accounts currently serving chat,
+# account maintenance, or LS maintenance by default. Set 0 only if you want
+# scheduled maintenance to run even when an account is busy.
+# WINDSURFAPI_BACKGROUND_MAINTENANCE_SKIP_BUSY=1
+
+# Native Cascade tool bridge. Default off because Cascade executes native
+# Read/Bash-style tools in the remote Windsurf workspace, while most clients
+# expect local execution.
+# v2.0.139 production canary scope is intentionally narrow: without an
+# explicit tool allowlist, only Bash / shell_command / run_command can route
+# through the native bridge. Read/Grep/Glob/WebSearch/WebFetch are protocol
+# matrix work, not production defaults. For local IDE tools (Claude Code,
+# Cline, Codex, opencode), keep the default emulation path unless you are
+# explicitly testing remote execution semantics.
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE=all_mapped
+# Optional gray gates for real testing:
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE_TOOLS=Bash
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE_MODELS=claude-4.5-haiku
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE_API_KEYS=your-test-api-key
+# Force bridge mode for mapped subsets only after the canary is proven:
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE=1
+# Emergency hard-off:
+# WINDSURFAPI_NATIVE_TOOL_BRIDGE_OFF=1
+# Smoke an already-running native bridge deployment with:
+# API_KEY=... BASE_URL=http://127.0.0.1:3003 npm run smoke:native-bridge
+# Protocol trace is lab-only. For Read wrapper reverse engineering, prefer the
+# dedicated child summary over global raw string dumps:
+# WINDSURFAPI_PROTO_TRACE=1
+# WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_STRINGS=0
+
+# Optional special-agent backend for models that do not work through direct
+# Cascade chat (currently swe-1.6 / swe-1.6-fast / adaptive / arena-*).
+# Default off. When enabled, the first PoC backend uses Devin CLI print mode:
+#   devin -p "<prompt>"
+# Install/configure Devin CLI separately on the host/container and point this
+# path at it. Do not bake it into the base image unless you want that runtime
+# dependency for every deployment.
+# WINDSURFAPI_SPECIAL_AGENT_BACKEND=devin-cli
+# DEVIN_CLI_PATH=devin
+# DEVIN_CLI_MODE=print
+# DEVIN_MAX_PROCS=1
+# DEVIN_QUEUE_TIMEOUT_MS=30000
+# DEVIN_TIMEOUT_MS=600000
+# Pass the checked-out Windsurf account apiKey to Devin CLI as WINDSURF_API_KEY.
+# Set to 0 only when the CLI has its own login/session and you understand that
+# the HTTP server still expects a normal WindsurfAPI account pool.
+# DEVIN_CLI_USE_ACCOUNT_POOL=1
+# Print mode refuses caller-local tools/media by default; ACP bridging should
+# be used before enabling these in production.
+# DEVIN_CLI_ALLOW_CLIENT_TOOLS=0
+# DEVIN_CLI_ALLOW_MEDIA=0
+# After configuring Devin CLI/ACP, validate the route with:
+# API_KEY=... BASE_URL=http://127.0.0.1:3003 npm run smoke:special-agent
+
+# ========== Dashboard ==========
+# Dashboard password — protects /dashboard and all /dashboard/api/* endpoints.
+# If empty AND API_KEY is also empty, dashboard is completely open (anyone can
+# view accounts, API keys, logs, and trigger updates). Set this for any
+# internet-facing deployment.
+DASHBOARD_PASSWORD=
+
+# ========== Astraflow (OpenAI-compatible, 200+ models — https://astraflow.ucloud-global.com) ==========
+# Global endpoint (env: ASTRAFLOW_API_KEY)  — base URL: https://api-us-ca.umodelverse.ai/v1
+ASTRAFLOW_API_KEY=
+# China endpoint  (env: ASTRAFLOW_CN_API_KEY) — base URL: https://api.modelverse.cn/v1
+ASTRAFLOW_CN_API_KEY=
+
+# ========== Advanced ==========
+CODEIUM_API_URL=https://server.self-serve.windsurf.com
+DEFAULT_MODEL=claude-4.5-sonnet-thinking
+MAX_TOKENS=8192
+LOG_LEVEL=info
+
+# ========== Cascade Reuse (single-user Claude Code optimization) ==========
+# Caller-based fallback: when fingerprint misses, reuse the latest cascade
+# for the same caller+model. Set to 1 for single-user Claude Code setups.
+CASCADE_REUSE_BY_CALLER=0
+# Max pool entries. Single-user setups can set to 1-5.
+CASCADE_POOL_MAX=500
+# Don't hash system prompt (reduces fingerprint drift from Claude Code's
+# dynamic system prompt). Already defaults to 0.
+# CASCADE_REUSE_HASH_SYSTEM=0
+
+# ========== Security ==========
+# Allow private/internal hosts (e.g., 192.168.x.x, 10.x.x.x, localhost) in proxy tests.
+# Set to 1 for local deployments where you need to test proxies on private networks.
+# Leave empty or set to 0 for public-facing deployments (default: only public hosts allowed).
+ALLOW_PRIVATE_PROXY_HOSTS=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 andersonviudes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# windsurf-openai
+
+Turn [Windsurf](https://windsurf.com) (formerly Codeium) cloud models into standard, drop-in APIs:
+
+- `POST /v1/chat/completions` — OpenAI-compatible (any OpenAI SDK)
+- `POST /v1/messages` — Anthropic-compatible (Claude Code / Cline / Cursor)
+- `POST /v1/responses` — OpenAI Responses API
+- `GET  /v1/models` — list available models
+
+100+ models (Claude, GPT-5.x, Gemini, Grok, Qwen, Kimi, GLM, SWE, …). Pure Node.js, **zero npm dependencies**, requires Node `>=24`.
+
+> Fork of [dwgx/WindsurfAPI](https://github.com/dwgx/WindsurfAPI), rewritten in English with a `windsurf-api` CLI. MIT licensed — see [LICENSE](LICENSE).
+
+## Quick start (CLI)
+
+```bash
+npm install -g .                            # from a clone (or `npm link` for dev)
+
+windsurf-api install                        # write .env, create dirs, download the Language Server
+windsurf-api login --token <windsurf-token> # add an account (get the token below)
+windsurf-api start --port 3003              # boot the proxy
+```
+
+Other commands: `windsurf-api accounts` (list the pool), `status` (pool summary), `--help` (all flags). Flags like `--port`, `--api-key`, `--ls-binary` override `.env`.
+
+> The Language Server is Linux/macOS only. On Windows, `install` scaffolds `.env` and the directories but skips the download — use Docker or WSL2, or point `--ls-binary` at a Windsurf desktop `language_server` binary. Prebuilt single-file executables are also attached to each [GitHub Release](https://github.com/andersonviudes/windsurf-openai/releases).
+
+## Docker
+
+```bash
+cp .env.example .env
+docker compose up -d --build
+docker compose logs -f
+```
+
+State persists under `./.docker-data/`; the container auto-downloads the Language Server on first boot if it isn't already there.
+
+## Add an account
+
+Grab your token from [windsurf.com/show-auth-token](https://windsurf.com/show-auth-token), then either:
+
+```bash
+windsurf-api login --token YOUR_TOKEN
+# or over HTTP:
+curl -X POST http://localhost:3003/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"token": "YOUR_TOKEN"}'
+```
+
+Or open the dashboard at `http://YOUR_IP:3003/dashboard` and sign in with Google / GitHub / email — it adds the account to the pool automatically.
+
+## Use it
+
+OpenAI SDK:
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://YOUR_IP:3003/v1", api_key="YOUR_API_KEY")
+r = client.chat.completions.create(
+    model="claude-sonnet-4.6",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(r.choices[0].message.content)
+```
+
+Claude Code:
+
+```bash
+export ANTHROPIC_BASE_URL=http://YOUR_IP:3003
+export ANTHROPIC_API_KEY=YOUR_API_KEY
+claude
+```
+
+The OpenAI surface supports streaming, tool/function calling, JSON mode, image inputs, and real token usage. List models with `GET /v1/models`.
+
+> **Cursor** blocks model names containing `claude` client-side — use aliases like `sonnet-4.6` or `opus-4.6` instead. GPT / Gemini names work as-is.
+
+## Configuration
+
+Configure via environment variables (or `.env`). The common ones:
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3003` | Service port |
+| `API_KEY` | empty | Required on requests when set; empty disables auth |
+| `HOST` | `0.0.0.0` | Bind host (`127.0.0.1` for localhost-only) |
+| `DATA_DIR` | `~/.windsurf-api` | Persisted state and logs (`/data` in Docker) |
+| `DEFAULT_MODEL` | `claude-4.5-sonnet-thinking` | Model used when none is given |
+| `MAX_TOKENS` | `8192` | Default max response tokens |
+| `LS_BINARY_PATH` | `/opt/windsurf/language_server_linux_x64` | Path to the Language Server binary |
+| `DASHBOARD_PASSWORD` | empty | Dashboard password (empty = none) |
+
+See [`.env.example`](.env.example) for the full, annotated list (proxy, account pool, LS pool tuning, lab/experimental flags).
+
+### Config file (fallback below ENV)
+
+Instead of (or alongside) environment variables, you can drop a `config.json` next to the app — a
+flat JSON file keyed by the same names as the env vars. It is a **fallback**: anything already set
+in the environment wins, and the file only fills what's missing. Precedence is:
+
+```
+CLI flags  >  real ENV  >  .env  >  config.json  >  built-in defaults
+```
+
+```json
+{
+  "PORT": "3003",
+  "API_KEY": "sk-...",
+  "LS_BINARY_PATH": "/opt/windsurf/language_server_linux_x64",
+  "CODEIUM_AUTH_TOKEN": "..."
+}
+```
+
+Copy [`config.example.json`](config.example.json) to `config.json` (it's gitignored — it holds
+secrets). `windsurf-api install` writes both `.env` and `config.json` for you. Keys prefixed with
+`_` are treated as comments and ignored.
+
+**Required to boot:** the server refuses to start unless at least one auth source is configured —
+`CODEIUM_API_KEY`, `CODEIUM_AUTH_TOKEN`, `CODEIUM_EMAIL` + `CODEIUM_PASSWORD`, or a non-empty
+`accounts.json`. Set `WINDSURFAPI_ALLOW_NO_AUTH=1` to start empty and add accounts later from the
+dashboard.
+
+## Dashboard
+
+`http://YOUR_IP:3003/dashboard` — account management, subscription/balance detection, model whitelist/blacklist, per-account proxies, live logs, and latency/usage stats.
+
+## How it works
+
+The proxy translates each request into Windsurf's gRPC/Cascade protocol and relays it through a locally-spawned Language Server, managing a self-healing account pool (round-robin, rate limits, failover) along the way.
+
+This is a **chat API, not an IDE agent** — it only passes `tool_use` / `tool_result` through. Your client (Claude Code, Cline, Cursor, Aider) is what actually reads and writes local files. If the model says it "can't access the filesystem", that's expected: drive it from one of those clients.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/windsurf-api.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Published CLI launcher. The real CLI is the built bundle at dist/app/cli.js
+// (produced by scripts/build-js.mjs at publish time). This thin shim only exists
+// so the package has a bin/ dir; importing the bundle runs its dispatch().
+import '../dist/app/cli.js';

package/config.example.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Optional config file: a flat JSON fallback BELOW environment variables. Copy to config.json (gitignored) and fill in. Precedence: CLI flags > real ENV > .env > config.json > built-in defaults. Keys mirror .env.example exactly. The server refuses to start with no auth source (CODEIUM_API_KEY / CODEIUM_AUTH_TOKEN / CODEIUM_EMAIL+CODEIUM_PASSWORD / a non-empty accounts.json) unless WINDSURFAPI_ALLOW_NO_AUTH=1.",
+
+  "PORT": "3003",
+  "HOST": "0.0.0.0",
+  "API_KEY": "",
+  "DATA_DIR": "",
+
+  "CODEIUM_API_KEY": "",
+  "CODEIUM_AUTH_TOKEN": "",
+
+  "LS_BINARY_PATH": "/opt/windsurf/language_server_linux_x64",
+  "LS_PORT": "42100",
+
+  "DASHBOARD_PASSWORD": "",
+
+  "DEFAULT_MODEL": "claude-4.5-sonnet-thinking",
+  "MAX_TOKENS": "8192",
+  "LOG_LEVEL": "info",
+  "ALLOW_PRIVATE_PROXY_HOSTS": ""
+}