Self-Host WindsurfAPI with Localtonet

Understand the WindsurfAPI to DevinAPI transition

The project now describes itself as “WindsurfAPI · DevinAPI.” Its current project site says that WindsurfAPI grew into DevinAPI as the default architecture moved toward a direct Devin cloud connection. The GitHub repository remains named WindsurfAPI, and commands, directory names, Windows assets, and older documentation may still use that name. In this tutorial, “the project” means the software in the dwgx/WindsurfAPI repository, while “DevinAPI” describes its current product and architecture direction.

This is more than a naming change. The current default path uses DEVIN_CONNECT=1 to communicate directly with the Devin cloud path over HTTP. It does not require the optional Windsurf Language Server binary. The older Cascade architecture remains available as a second transport path and uses a local Language Server to communicate with the Windsurf cloud. Operators should therefore determine which transport a selected release is using before diagnosing platform, binary, or upstream problems.

Release-sensitive behavior matters throughout this guide. The examples below are pinned to the project’s v3.9.29 release. That release reports no API-breaking change and no required configuration migration from its immediate predecessor, but it is still safer to validate the exact tag you deploy. Consult the project’s English README and release history before substituting a newer tag.

What the HTTP service exposes

The project documents an HTTP service on port 3003 by default. Depending on the selected release and enabled features, its documented API surface includes:

• POST /v1/chat/completions for OpenAI-compatible chat requests.
• POST /v1/completions for the legacy OpenAI Completions shape.
• POST /v1/responses for the OpenAI Responses format.
• POST /v1/messages for Anthropic-compatible clients.
• Routes beneath /v1beta/models/ for Gemini-compatible requests.
• GET /v1/models for authenticated model discovery.
• A management interface beneath /dashboard.

Protocol compatibility does not guarantee compatibility with every client release, request field, model, or upstream capability. The project controls the translation layer, and upstream behavior may change independently. Test the specific route, client version, account, and model combination you intend to use instead of treating an accepted request format as a universal compatibility promise.

Where agent actions actually run

WindsurfAPI or DevinAPI is an HTTP translation and account-access service. It does not itself become the file-editing environment for Claude Code or Cline. When an agent client receives a tool request to read a file, modify source code, or execute a command, that client performs the action where the client is running and under the client process’s local permissions.

This boundary affects security design. An API key controls access to the HTTP service, but it does not constrain the filesystem permissions of an authorized agent client. Protect the API endpoint and separately restrict the client’s workspace, operating-system account, command permissions, repositories, and credentials.

Prerequisites and deployment choices

Choose one deployment method before configuring remote access. Host and Docker deployments require a checkout of the repository. The packaged Windows route uses a release asset instead. This guide uses v3.9.29 so that setup behavior can be evaluated against a specific release rather than the changing master branch.

For a host installation, prepare:

• A machine on which you are authorized to install and run the project.
• Node.js 20 or newer.
• Git for cloning and checking out the selected release.
• Bash if you intend to use setup.sh, install-ls.sh, or update.sh.
• Outbound network access required by the selected project transport and authorized account.
• An account that the selected project release accepts and that you are authorized to use.
• Permission to use local port 3003, or a documented alternative set with PORT.
• A Localtonet account and client installation for the later tunneling stage.

Docker users need Docker Engine with the Compose plugin. They do not need a host-level Node.js runtime for the application container. Windows users who select a packaged release should verify that the chosen tag actually contains the documented Windows asset and should read that release’s notes before running it.

Install and start the pinned v3.9.29 release

Pinning a release gives you a reproducible starting point. It does not freeze upstream account behavior or guarantee that every documented model will remain available, but it prevents an unreviewed commit on master from entering the initial installation.

Option A: run setup.sh on a Node.js host

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

git fetch --tags
git checkout v3.9.29

bash setup.sh

node src/index.js

Option B: direct Node.js startup without setup.sh

The project’s current site also documents a direct zero-runtime-dependency startup path. After cloning and checking out v3.9.29, copy the example configuration and start the service:

cp .env.example .env
node src/index.js

Review .env before starting. For the direct host path, the project site documents an empty API_KEY as no API authentication and an empty DASHBOARD_PASSWORD as an unprotected dashboard. This differs from the documented Docker Compose fail-closed behavior. Populate both fields with strong, unrelated values.

The current architecture describes DEVIN_CONNECT=1 as the direct Devin cloud path and the default direction. If the checked-out release’s example file differs, follow the comments shipped with that tag and investigate the discrepancy before continuing.

Option C: Docker Compose

Use the same pinned checkout, then prepare the environment and start the container:

cp .env.example .env
docker compose up -d --build
docker compose logs -f

The documented Compose defaults use DEVIN_CONNECT=1, so the container does not run or automatically download the optional Language Server on the normal direct path. The project documents the following persistent mounts:

• ./.docker-data/data for account, proxy, statistics, runtime, model-access, and log data.
• ./.docker-data/opt/windsurf for optional Language Server files and data.
• ./.docker-data/tmp/windsurf-workspace for the temporary workspace.

Docker uses /data as its documented internal data location. The project supports changing the location with DATA_DIR, but storage changes should preserve the intended mounts and backup coverage.

Option D: Windows release package

For Windows, open the project’s v3.9.29 release page and confirm which Windows assets are attached. The current project site describes both a tray package and a console executable, but packaging can change between releases. Use only an asset published with the tag you reviewed.

The current Windows documentation says first launch generates API_KEY and DASHBOARD_PASSWORD in a local .env, uses DEVIN_CONNECT=1, and binds to 127.0.0.1 by default. Verify the generated values and actual listening address on your selected release. Do not change HOST to 0.0.0.0 merely to use Localtonet when the Localtonet client runs on the same Windows machine. A tunnel can target 127.0.0.1:3003 directly.

Configure authentication and an authorized account

The service has at least three credential boundaries: the client API key, the dashboard password, and the account credential or session token used for the selected upstream path. Never reuse one value across these boundaries.

Set the API key

Configure a strong, unique API_KEY. Anthropic-compatible requests normally submit it using x-api-key. OpenAI-compatible requests normally submit it as a bearer token. Gemini-compatible clients may use the header expected by that project route. Confirm exact header handling against the selected release.

The API key belongs to your self-hosted service. It is not an upstream account token. Do not place an upstream session token in Claude Code, Cline, Cursor, shell examples, public environment files, or client-side browser code.

Set the dashboard password

Configure a separate strong DASHBOARD_PASSWORD. The dashboard is an administrative surface and may expose account state, settings, model controls, logs, or other operational data according to the installed version. Protect it even if you expect to use only API routes.

Add an account you are authorized to use

Open http://localhost:3003/dashboard, authenticate, and use the account workflow provided by the selected release. Current project materials discuss Devin session tokens and dashboard-assisted account functions, but accepted methods can change. Follow the interface and documentation shipped with the tag you deployed.

Account compatibility, model discovery, available tiers, rate limits, and upstream access are controlled by the project and upstream service. Do not assume that every Windsurf or Devin account type will work, that every displayed model is usable, or that an account permits shared access. Use only an account you own or are explicitly authorized to operate.

Verify the local API before creating a tunnel

Local verification separates application failures from tunnel failures. A Localtonet HTTP tunnel forwards requests to the configured local target, but it cannot start the Node.js process, correct an invalid account, grant a model entitlement, or repair an incorrect client header.

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 failures by layer. A connection refusal means the service is not reachable at the specified host and port. An HTTP authentication response proves that an application answered, but the supplied credentials were absent or invalid. An account or model error after successful API authentication usually points to account health, entitlement, project compatibility, upstream availability, or rate limits.

Connect Claude Code and Cline locally

Claude Code

For the project’s Anthropic-compatible route, set Claude Code’s base URL to the server origin. Do not append /v1/messages, because the client constructs its request path.

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

This configures a Claude Code process as a client of an Anthropic-compatible endpoint. It is not the same feature as Anthropic’s Claude Code self-hosted environments. That separate feature concerns where Claude Code cloud sessions execute and has its own organization, runner, plan, and networking requirements.

Cline

For an OpenAI-compatible provider in Cline, use the local base URL:

http://localhost:3003/v1

Supply the self-hosted service’s API key and select a model identifier returned by your authenticated /v1/models request. Cline’s provider labels and interface can change, so use the current OpenAI-compatible configuration rather than depending on an old menu location.

If your Cline release supports an Anthropic-compatible provider, the project also documents /v1/messages. Choose one protocol, follow that provider’s base-URL convention, and verify a minimal request before enabling tools.

Expose the verified service through Localtonet

Once the local dashboard, authenticated API request, and unauthorized-request tests all behave correctly, add the connectivity layer. Our Localtonet client establishes an outbound connection to a Localtonet relay server. The resulting HTTP tunnel provides a public HTTPS address without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

Run the Localtonet client on the same host as the API when practical. That allows the tunnel to target 127.0.0.1:3003 without changing the application to listen on all network interfaces. If the Localtonet client runs on another device, the service must listen on and be reachable through an authorized private network address from that device.

For the complete product workflow and current dashboard behavior, consult the Localtonet HTTP tunnel documentation. HTTP process types may provide a random subdomain, a supported custom subdomain, or a custom domain. Check the current dashboard and documentation for option availability and any DNS requirements.

If the assigned origin is 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

An OpenAI-compatible Cline configuration would use:

https://YOUR-ASSIGNED-HOST/v1

These are placeholders, not real Localtonet addresses. Copy the actual address from the running tunnel.

Routine operations, controlled updates, and troubleshooting

Keep the service available deliberately

A foreground node src/index.js process is useful during installation because its logs remain visible, but it stops when the terminal exits. The project documents PM2 as an optional process manager. If you use PM2 or another service manager, test startup, shutdown, log retention, and restart behavior locally before depending on unattended remote access.

Docker operators can inspect state with:

docker compose ps
docker compose logs -f

Preserve the documented persistent directories when replacing a container. Backups may contain account data and other secrets, so store and transfer them with the same protections as the live installation.

Treat update.sh as project-controlled and version-sensitive

The project provides update.sh, but it is not a passive package update. The project documents that the script can pull repository changes, invoke install-ls.sh to update the optional Language Server binary, stop PM2, terminate a residual process using port 3003, restart the service, and perform a health check. Those actions can change code, replace an optional binary, interrupt another process, and move a carefully pinned checkout.

If you intentionally accept the project-controlled update behavior, the documented invocation is:

cd WindsurfAPI
bash update.sh

After updating, do not restore public access based only on the script’s health check. Locally verify the dashboard login, authenticated model discovery, a minimal model request, and rejection of missing and invalid API credentials. Confirm the expected DEVIN_CONNECT mode, data persistence, process manager state, listening address, and port. Only after those regression checks pass should you restart the Localtonet tunnel and repeat the authorized and unauthorized tests through its public URL.

Diagnose failures by layer

Reduce the exposed surface

When the Localtonet client and API run on the same machine, keep the application bound to loopback where the selected deployment supports it. Avoid opening port 3003 directly on the router or host firewall. If remote clients need only API access, do not use the public dashboard routinely, even though both surfaces may share the same application origin.

Run the service under a non-administrative operating-system account where practical. Restrict access to its environment and data files. Separate agent workspaces from unrelated personal or production files. Users with sufficient local process or filesystem access may be able to read service credentials regardless of network controls.

Frequently asked questions