Connect the Windsurf IDE to a Remote FreeBSD System over SSH

Pair programming with an AI agent under close supervision will drastically improve your efficiency and throughput at completing tasks. While at the same time providing you with an interactive learning environment for new skills or improving existing ones. I'm currently a fan of Windsurf IDE with its Cascade AI. However it does not natively run on FreeBSD (despite it being a VSCode fork).

The next best thing is to connect to a remote FreeBSD development server from Windows (yes Windows! We do not use Linux here!). However there are some hoops to jump through. This guide explains the steps to get full Cascade functionality working with FreeBSD over SSH.

This guide is also available as an Agent Skill (an open standard) that you can use to automate the setup process.

Requirements

• FreeBSD 15.0 or later (required for inotify emulation)
• SSH access to the FreeBSD machine
• Windsurf IDE installed on your local machine (I use Windows)

FreeBSD versions prior to 15.0 do not implement Linux inotify syscalls, which causes the Cascade language server to fail with "function not implemented" errors. If you're running an older version, you'll need to upgrade first.

Install Required Utilities

A few packages are needed before we begin. FreeBSD doesn't include sudo by default, so we'll install security/sudo first along with the other required packages. Note that security/doas (the modern alternative commonly used on FreeBSD) won't work here since Cascade specifically invokes sudo.

Run these commands as root:

pkg install sudo flock bash curl

Add your user to the wheel group and enable passwordless sudo access. This allows Cascade to operate in turbo mode without prompting you to enter a password:

pw groupmod wheel -m yourusername
echo '%wheel ALL=(ALL:ALL) NOPASSWD: ALL' > /usr/local/etc/sudoers.d/yourusername

You'll also need to change your default shell on the FreeBSD system to Bash. Windsurf expects shells/bash, and the default FreeBSD shell (sh) will cause issues.

chsh -s /usr/local/bin/bash

Enable Linux Compatibility Layer

Windsurf's server components are Linux binaries, so you'll need the Linux compatibility layer enabled.

sudo kldload linux64
sudo sysrc linux_enable="YES"
sudo service linux start

The first command loads the 64-bit Linux kernel module. The second makes it persistent across reboots.

Install Linux Userland (Rocky Linux 9)

As of this writing, Rocky Linux 9 (emulators/linux_base-rl9) provides glibc 2.28+, which is required by Windsurf's Node.js runtime. Do NOT use CentOS 7 - its glibc is too old and you'll see errors like GLIBC_2.28 not found.

sudo pkg install linux_base-rl9
sudo service linux restart

Manually Install Windsurf Server

Windsurf does not auto-install on FreeBSD. You must download and extract the Linux server manually. The commit ID and version numbers change with each Windsurf update, so you'll need to find the current values from Windsurf's connection logs.

To find the current commit ID and version:

• Attempt to connect with Windsurf
• Open the Output panel (Ctrl+Shift+U)
• Select Remote-SSH from the dropdown
• Look for lines containing DISTRO_COMMIT and DISTRO_WINDSURF_VERSION

Once you have those values, run the following commands on your FreeBSD server:

DISTRO_WINDSURF_VERSION="1.13.9"
DISTRO_COMMIT="a473c86f69ab6b6f98bc47437adc6263df8738d0"

mkdir -p ~/.windsurf-server/bin/${DISTRO_COMMIT}
cd ~/.windsurf-server/bin/${DISTRO_COMMIT}

curl -L -o windsurf-server.tar.gz \
  "https://windsurf-stable.codeiumdata.com/linux-reh-x64/stable/${DISTRO_COMMIT}/windsurf-reh-linux-x64-${DISTRO_WINDSURF_VERSION}.tar.gz"

tar -xzf windsurf-server.tar.gz --strip-components=1
rm windsurf-server.tar.gz

Replace the DISTRO_COMMIT and DISTRO_WINDSURF_VERSION values with what you found in the logs.

Verify the Server Works

Test that the server runs under Linux emulation:

~/.windsurf-server/bin/${DISTRO_COMMIT}/bin/windsurf-server --version

You should see output like:

1.106.0
a473c86f69ab6b6f98bc47437adc6263df8738d0
x64

Verify the Cascade Language Server Works

This is the critical test. If this fails, Cascade won't work.

~/.windsurf-server/bin/${DISTRO_COMMIT}/extensions/windsurf/bin/language_server_linux_x64 --version

If this fails with function not implemented, you are not running FreeBSD 15.0+ with inotify support.

Connect from Windsurf

With the server installed, connecting is straightforward:

• Open Windsurf on your local machine
• Open Command Palette (Ctrl+Shift+P)
• Run Remote-SSH: Connect to Host...
• Enter or select your FreeBSD host

Cascade should now be fully functional.

Configure Windsurf Terminal

By default, Windsurf's integrated terminal won't work correctly on FreeBSD because it looks for bash at /bin/bash, but FreeBSD installs bash to /usr/local/bin/bash. You'll need to update Windsurf's settings on your local machine.

Open Windsurf settings (Ctrl+,) and add the following to your settings.json:

"terminal.integrated.profiles.linux": {
    "bash": {
        "path": "/usr/local/bin/bash",
        "icon": "terminal-bash"
    }
},
"terminal.integrated.defaultProfile.linux": "bash"

This tells Windsurf where to find bash on FreeBSD and sets it as the default terminal profile for Linux-compatible remote hosts.

SSH Configuration (Optional)

For passwordless authentication, generate an SSH key pair on your local machine:

ssh-keygen -t ed25519 -C "your_email@example.com"

Accept the default location and optionally set a passphrase. Then copy the public key to your FreeBSD server:

ssh-copy-id user@freebsd-host

On Windows, if ssh-copy-id is not available, you can manually append your public key to the server:

type %USERPROFILE%\.ssh\id_ed25519.pub | ssh user@freebsd-host "cat >> ~/.ssh/authorized_keys"

For easier connections, add an entry to your SSH config file. On Windows, this is %USERPROFILE%\.ssh\config. On Linux/MacOS, it's ~/.ssh/config.

Host freebsd-dev
    HostName 192.168.1.233
    User admin
    IdentityFile ~/.ssh/id_ed25519

Then you can simply select freebsd-dev from the host list.

Known Issues

Kernel Messages in dmesg

You may see messages like the following in dmesg:

linux: jid 0 pid 2598 (node): syscall io_uring_setup not implemented
linux: jid 0 pid 2602 (language_server_lin): unsupported prctl option 1398164801
linux: jid 0 pid 2690 (libuv-worker): unsupported ioctl TIOCGPTPEER

These are harmless. The Linux compatibility layer logs messages when applications attempt to use syscalls or ioctls that aren't implemented. Windsurf and Cascade function correctly despite these warnings.

Updates

When you update Windsurf it will attempt to auto-install itself, and it will fail. Just repeat the server installation steps by grabbing the latest commit ID and version.

Enjoy

If you found this helpful, you can say thanks by signing up for Windsurf using my referral link.