> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Windsurf

> Connect to Ona environments using Windsurf editor.

[Windsurf](https://windsurf.com/) connects to Ona environments using the same [Ona extension](https://marketplace.visualstudio.com/items?itemName=gitpod.gitpod-flex) as VS Code. All [VS Code features](https://ona.com/docs/ona/editors/vscode.md) (rebuild, port forwarding, automations) work in Windsurf.

> [!NOTE]
>
> When reaching out to support, specify that you are using Windsurf as your editor.

## Prerequisites

1. [Windsurf](https://windsurf.com/) installed on your machine.
2. The [Ona extension](https://marketplace.visualstudio.com/items?itemName=gitpod.gitpod-flex) installed in Windsurf.
3. The [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension installed in Windsurf.

## Opening an environment

Select **Windsurf** from the editor dropdown by clicking the dropdown arrow next to the Open button on the action bar.

Windsurf opens via the `windsurf://` URI handler. On first use, Windsurf prompts you to install the Ona extension and authenticate. This is the same flow as [VS Code setup](https://ona.com/docs/ona/editors/vscode.md#first-time-setup).

## Windsurf AI works over SSH

Windsurf's AI features work in Ona environments as they do locally:

* **Cascade**: AI assistant for multi-step tasks
* **Flows**: context-aware actions triggered from the editor
* **Supercomplete**: code completions
* **Chat**: inline AI chat for code questions

Windsurf AI communicates with Windsurf's cloud services directly over the SSH connection. No Ona-specific configuration is needed.

## Extension and settings

Extensions configured via `customizations.vscode.extensions` in your `devcontainer.json` apply to Windsurf. See [VS Code and forks](https://ona.com/docs/ona/editors/overview.md#vs-code-and-forks) for details.

## Troubleshooting

> [accordion] Windsurf does not open
>
> The `windsurf://` URI handler is not registered on your system, or Windsurf is not installed.
>
> * **Linux**: Verify a Windsurf desktop entry exists in `~/.local/share/applications` or `/usr/share/applications`. If missing, reinstall Windsurf.
> * **All platforms**: Refresh the browser page, or test in a different browser to rule out browser-specific issues.

> [accordion] Connection issues
>
> The [VS Code troubleshooting guide](https://ona.com/docs/ona/editors/vscode.md#troubleshooting) applies to Windsurf, including log export (`Ona: Export all logs`) and authentication issues.

> [accordion] General issues
>
> 1. Check the `Ona` output view for errors.
> 2. Check your network settings. VPN or firewall can interfere.
> 3. When sharing reports with support:
>    * Set log level to Trace via `Developer: Set Log Level...`
>    * Use `Ona: Export all logs` from the problematic window.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.