Skip to main content
Windsurf connects to Ona environments using the same Ona extension as VS Code. All VS Code features (environment details, rebuild, port forwarding, automations) work in Windsurf.
When reaching out to support, specify that you are using Windsurf as your editor.

​
Prerequisites

  1. Windsurf installed on your machine.
  2. The Ona extension installed in Windsurf.
  3. The 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.

​
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 for details.

​
Troubleshooting

​
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.

​
Connection issues

The VS Code troubleshooting guide applies to Windsurf, including log export (Ona: Export all logs) and authentication issues.

​
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.