Lying to Zed to get its remote server running on FreeBSD

Independent developers running FreeBSD can now operate Zed editor remote development servers through the operating system binary compatibility layer. According to hayzam.com's report, developers have routed remote editing sessions to FreeBSD servers using a shell wrapper and a kernel directory fix. The approach establishes full project tree visibility without waiting for an official FreeBSD release from Zed.

This report details how an environment shim, Linuxulator packages, and kernel patch ec6629628cb restore remote editing functionality. The workflow serves engineers and systems programmers who require responsive editors without intrusive generative assistance. Readers will understand how to configure host compatibility, resolve directory parsing crashes, and inspect underlying filesystem batch calculations.

01Linuxulator setup and the custom uname wrapper

Zed features a settings toggle named disable_ai, paralleling the chat.disableAIFeatures setting recently added to Visual Studio Code. Developers avoiding heavy editor overhead and invasive autocompletions often rely on modular test harnesses like OpenCode for regression testing. Because Zed lacks an official FreeBSD remote package, users deploy the Linux binary through FreeBSD Linuxulator compatibility subsystem.

Activating binary compatibility requires configuring sysrc to set linux_enable to YES, starting the background service, and installing the linux_base-rl9 package. Administrators verify the 64-bit kernel translation module by running kldstat with the linux64 flag. Standard SSH access on the FreeBSD host provides the operational foundation required to run the remote workspace server.

When establishing SSH connections, Zed detects the host platform by executing uname with the ms and sm arguments. Because an answer of FreeBSD amd64 causes Zed to abort, users deploy a small wrapper at ~/.local/bin/uname. This script outputs Linux x86_64 for those specific arguments while forwarding all other requests directly to /usr/bin/uname.

02Remote SSH connection and directory reading failures

Deploying the custom uname wrapper requires exporting ~/.local/bin into non-interactive environment paths using ~/.zshenv or an equivalent shell configuration. Once connected over SSH, Zed uploads its Linux server package directly into the ~/.zed_server directory on the remote machine. Engineers can monitor server startup by tracking log files located at ~/.local/share/zed/logs/server-workspace-*.log using the tail command.

Although the remote Linux server starts successfully, unpatched operating system kernels fail to populate the file tree, displaying an empty project. The server log records an error processing entry failure alongside an underlying Invalid argument error labeled as os error 22. This failure halts directory parsing and prevents the workspace explorer from indexing repository contents.

Zed fetches folder listings in batches, assigning a 768-byte buffer to receive sequential directory names from the host operating system. When compatibility software attempts to fill that memory space, mismatches between kernel records and buffer boundaries trigger an immediate operating system fault. Without the required kernel correction, the editor cannot display workspace files.

03Buffer sizing mismatch and missing directory entries

The directory read failure stems from how the Linuxulator requests directory entries from the underlying filesystem. The issue resembles a teacher taking attendance by writing groups of four student names onto a note holding only six entries. Because six is not divisible by four, reading two full groups crosses off eight names while fitting only six.

The translator cannot return the six fitting names while retaining the remainder because the filesystem offset already advanced past the batch. If the kernel silently discarded overflow entries instead of raising an error, directory listings would lose files without warning. In testing, suppressing the error caused 112 of 1,002 files to vanish completely from the listing.

To prevent silent data corruption, the translation layer raises an explicit EINVAL error code when entries overflow the caller buffer. Zed detects this returned failure, concludes that the directory cannot be read, and leaves the workspace folder completely blank. Resolving the breakdown requires preventing the kernel from requesting more entries than the buffer accommodates.

04Linux file compatibility regression in kernel getdents

The directory parsing failure was traced to a kernel regression introduced in February 2026 under commit 110f2567cb51 for PR 292282. That change attempted to resolve invalid NFS directory entries by rounding native read requests up to 512-byte blocks. The modification updated sys/compat/linux/linux_file.c across linux_getdents and linux_getdents64 by replacing min(args->count, MAXBSIZE) with min(roundup2(args->count, DEV_BSIZE), MAXBSIZE).

Rounding buffer requests up to the DEV_BSIZE boundary creates failures whenever an application supplies a buffer that is not a 512-byte multiple. In Zed, the client provides a 768-byte buffer, prompting the kernel to round the read request up to 1,024 bytes. Converted records exceeding caller capacity trigger EINVAL after kern_getdirentries has already advanced the directory offset.

Rewinding the directory seek pointer across partial batches is impossible without corrupting traversal state. Linux directory headers are structurally smaller than FreeBSD equivalents, with dirent64 headers measuring 19 bytes against 24 bytes in FreeBSD. Because both formats round records up to 8-byte boundaries, native batches constrained to the caller buffer translate safely into Linux format.

05Kernel directory repair across FreeBSD release branches

Developer Hayzam submitted kernel patch ec6629628cb, which underwent review under differential revision D60760. The updated logic evaluates args->count against DEV_BSIZE, applying min(args->count, MAXBSIZE) for larger requests and reserving roundup2(args->count, DEV_BSIZE) for smaller buffers. This conditional branch guarantees that requested directory batches never exceed the buffer boundaries specified by user applications.

While an initial draft addressed only linux_getdents64, the full patch corrected both legacy 32-bit getdents and 64-bit getdents routines. Expanding the fix resolved all 86 failing test cases across the kernel validation suite. Commit reviewers Kyle Evans and Mark Johnston guided the implementation through the project technical standards.

The FreeBSD release engineering team merged the repair into main, stable/15, and releng/15.2, scheduling it for distribution in 15.2-RELEASE. System administrators can confirm the patched kernel is active by checking system build information with uname -v. Once installed, the fix enables seamless remote Zed editing sessions across FreeBSD infrastructure.