> ## 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](/ona/editors/vscode) (environment details, rebuild, port forwarding, automations) work in Windsurf.

<Note>When reaching out to support, specify that you are using Windsurf as your editor.</Note>

## 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](/ona/editors/vscode#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](/ona/editors/overview#vs-code-and-forks) for details.

## Troubleshooting

<Accordion title="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>

<Accordion title="Connection issues">
  The [VS Code troubleshooting guide](/ona/editors/vscode#troubleshooting) applies to Windsurf, including log export (`Ona: Export all logs`) and authentication issues.
</Accordion>

<Accordion title="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.
</Accordion>