Self-Host WindsurfAPI with Localtonet

What WindsurfAPI does in this workflow

WindsurfAPI runs as an HTTP service on the host you control. Its documented default service port is 3003. Instead of requiring every client to understand the project's upstream communication mechanism, it exposes familiar API shapes that existing development tools and SDKs can call.

The supported routes documented by the project include POST /v1/chat/completions for OpenAI-compatible chat requests, POST /v1/responses for the OpenAI Responses format, POST /v1/messages for Anthropic-compatible clients, and routes below /v1beta/models/ for Gemini-compatible requests. It also documents the legacy POST /v1/completions route. Available models depend on the account connected to the service, so this guide deliberately does not hardcode a model name.

Claude Code and Cline are clients in this design. WindsurfAPI passes model messages, tool requests, and tool results between the client and its configured upstream account. File reading, editing, command execution, and similar agent actions occur in the client environment, not inside the WindsurfAPI HTTP server. This distinction matters when deciding where to run each component and what permissions to grant.

Prerequisites and deployment choices

The most direct documented installation path uses Git, Bash, and Node.js. The project's current deployment documentation specifies Node.js 20 or newer. You also need outbound network access from the host so it can clone the repository and communicate with the upstream service selected by your configuration.

For the script-based installation in this guide, prepare:

• A machine on which you are authorized to install and run software.
• Node.js 20 or newer.
• Git for cloning and updating the repository.
• Bash for setup.sh and the project's maintenance scripts.
• An authorized Windsurf or Devin account compatible with the path you intend to use.
• Permission to use port 3003, or a deliberate alternative configured through the project's documented PORT setting.
• A Localtonet account and client installation for the later remote-access stage.

Docker users need Docker Engine with the Compose plugin instead of a host-level Node.js runtime. The supplied Compose configuration builds the application image and defines persistent mounts. The project documentation states that Compose defaults to the direct Devin connection path through DEVIN_CONNECT=1. In that mode, it does not run or automatically download the optional Language Server. If you intentionally disable that path and select the traditional Cascade route, Language Server installation and platform compatibility become separate requirements.

Install and start WindsurfAPI

The repository's quick-start workflow is the preferred starting point here because it prepares the host installation and generates the initial environment file. Run the commands from a shell on the machine that will host the service.

git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI

bash setup.sh

node src/index.js

If you prefer Docker Compose, copy the example environment file, review it, and then build and start the service:

git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI
cp .env.example .env
docker compose up -d --build
docker compose logs -f

The documented default mounts include ./.docker-data/data for account, proxy, statistics, runtime, model-access, and log data; ./.docker-data/opt/windsurf for optional Language Server files and data; and ./.docker-data/tmp/windsurf-workspace for the temporary workspace. The Docker configuration uses /data as its default internal data directory. The project documents DATA_DIR for changing that location, but adjust storage only after understanding the Compose mounts and backup implications.

Configure authentication and add an authorized account

WindsurfAPI has two distinct access surfaces. The API is used by Claude Code, Cline, SDKs, and other clients. The dashboard is an administrative surface used to manage accounts and service settings. Protecting only the API while leaving the dashboard open would still expose sensitive operational controls, so configure and test both.

Protect the API

The project uses API_KEY for client authentication. Store a strong, unique value in .env or through the secret-management mechanism used by your deployment environment. A client using the Anthropic-compatible route supplies that key through x-api-key. OpenAI-compatible clients normally supply it as a bearer token.

Do not use a real upstream account token as the API key. These credentials serve different purposes. The API key authorizes a client to call your local WindsurfAPI service, while the account credential authorizes WindsurfAPI to use the account you have added.

Protect the dashboard

Set and retain a strong DASHBOARD_PASSWORD. The dashboard is available below /dashboard, and the project also documents an authentication route at /auth/login. Use the dashboard password only through the dashboard login flow. Do not place it in Claude Code, Cline, or an API request.

Add your authorized account

Open the local dashboard, authenticate, and use the account-management or login function presented by the installed version. Supply credentials or a session token only for an account that you own or have explicit authorization to operate. The interface and accepted login methods can change between project versions, so follow the labels shown by your running dashboard rather than assuming fields from an older screenshot.

After adding the account, confirm that it appears healthy and that the service can discover models available to that account. Model access varies by account tier. If a particular model is absent or rejected, do not assume that the tunnel, API route, or client is broken. First verify that the connected account is entitled to use that model.

Verify WindsurfAPI locally before creating a tunnel

Remote access should never be the first test. A Localtonet HTTP tunnel forwards traffic to the local target you configure, but it cannot repair an application that has not started, is listening on a different port, rejects its account, or has invalid credentials. Verify each layer locally so later failures have a clear boundary.

export WINDSURFAPI_KEY='REPLACE_WITH_YOUR_LOCAL_API_KEY'

curl \
  -H "Authorization: Bearer ${WINDSURFAPI_KEY}" \
  http://localhost:3003/v1/models

curl http://localhost:3003/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: ${WINDSURFAPI_KEY}" \
  -d '{
    "model": "REPLACE_WITH_AN_AVAILABLE_MODEL",
    "max_tokens": 64,
    "messages": [
      {
        "role": "user",
        "content": "Reply with the word ready."
      }
    ]
  }'

Interpret errors by layer. A connection refusal usually means no process is listening at the specified host and port. An HTTP authentication error indicates that the service is reachable but the API key or dashboard credentials are missing or incorrect. A model or account error after successful authentication points toward account health, entitlement, rate limits, or upstream communication rather than local networking.

Connect Claude Code and Cline locally

Once the direct API request works, configure your client against the local endpoint. Start locally even if the final goal is remote access. This separates client configuration errors from tunnel configuration errors.

Claude Code

WindsurfAPI documents the Anthropic-compatible base URL for Claude Code. Set the base URL to the server origin, not to /v1/messages, because the client appends the appropriate API path. Set the API key to the value configured for WindsurfAPI.

export ANTHROPIC_BASE_URL="http://localhost:3003"
export ANTHROPIC_API_KEY="REPLACE_WITH_YOUR_LOCAL_API_KEY"
claude

These variables configure the API endpoint used by that client process. They are not the same as Anthropic's separate self-hosted cloud-session environments. This tutorial concerns connecting a locally or remotely running Claude Code client to WindsurfAPI's Anthropic-compatible HTTP endpoint.

Cline

Cline can use an OpenAI-compatible provider configuration for this workflow. Configure its base URL as:

http://localhost:3003/v1

Supply the WindsurfAPI API key and choose a model identifier confirmed by your authenticated /v1/models response. Cline versions and provider menus can change, so use the current OpenAI-compatible provider entry rather than relying on an old menu location.

If the client supports an Anthropic-compatible provider, the project also documents /v1/messages. Choose one protocol and configure its corresponding base URL convention carefully. OpenAI-compatible clients generally expect the base URL to include /v1, while Claude Code's documented ANTHROPIC_BASE_URL value is the server origin.

Expose the verified HTTP service through Localtonet

At this point, WindsurfAPI should already respond correctly at http://localhost:3003. The next step is connectivity, not installation. With Localtonet, our client application establishes an outbound connection to a Localtonet relay server. The resulting HTTP tunnel provides a public HTTPS address without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

Run the Localtonet client on the WindsurfAPI host or on another device that can reach the host and port. If both applications run on the same machine, 127.0.0.1 and port 3003 are the clearest local target. If the client runs on a separate device, the WindsurfAPI service must be reachable from that device through an authorized private network address. Do not change the application to listen on every interface unless that is necessary and protected by your network controls.

For example, if the assigned address were represented by the placeholder https://YOUR-ASSIGNED-HOST, Claude Code would use:

export ANTHROPIC_BASE_URL="https://YOUR-ASSIGNED-HOST"
export ANTHROPIC_API_KEY="REPLACE_WITH_YOUR_WINDSURFAPI_KEY"
claude

Cline's OpenAI-compatible base URL would use the same assigned origin with /v1 appended:

https://YOUR-ASSIGNED-HOST/v1

These are placeholders, not real Localtonet addresses. Always copy the assigned URL from your running tunnel. You can review current tunnel categories and controls in the Localtonet documentation.

Routine operations, updates, and troubleshooting

Keep the service available deliberately

A foreground node src/index.js process is useful during installation because logs remain visible, but it stops when its terminal ends. The project documents PM2 as an optional process manager and provides an update script that can interact with PM2. If you adopt a process manager, configure it according to your operating system and validate restart behavior before relying on unattended access.

Docker operators can inspect current state and logs with:

docker compose ps
docker compose logs -f

Preserve the mounted data directories when rebuilding or replacing the container. Backups containing account information and configuration are sensitive and need the same access controls as the live data.

Update with a recovery plan

The repository provides update.sh. Its documented workflow pulls changes, updates the optional Language Server through install-ls.sh, stops PM2, clears a residual process on port 3003, restarts the application, and performs a health check. Because this can change both application code and runtime state, inspect the script and release notes before running it.

cd WindsurfAPI
bash update.sh

Back up the environment file and persistent data first, while protecting those backups as secrets. After an update, repeat local dashboard access, authenticated model discovery, a minimal message request, and the unauthorized-request test. Only then restart or continue using the Localtonet tunnel.

Diagnose common failures by layer

Reduce the exposed surface

If remote clients need only API access, avoid routinely opening the dashboard through a browser over the public address. The HTTP tunnel forwards paths for the same application origin, so application authentication remains the control protecting administrative routes. Use strong dashboard credentials, access administration only when needed, and stop the tunnel when remote API access is no longer required.

Apply least privilege to the host as well. Run WindsurfAPI under a non-administrative account where practical, restrict access to its data directory, limit which users can read process environments, and keep the agent client's workspace separate from unrelated files. If the host is shared, remember that users with sufficient process or filesystem access may be able to obtain application secrets regardless of network controls.

Frequently asked questions