[← README](../../README.md) · [Docs index](../README.md) · [Systems](README.md)

# FreeBSD

Both apps run on FreeBSD. The terminal app, `coxswain`, is a first-class build: one binary that
needs nothing beyond the base system, tested on every change. The desktop app, `coxswain-gui`,
is **experimental** on FreeBSD: it is built and tested on every change as well, and browsing,
the preview pane, Find, copy, move, the trash and the clipboard work, but it is built from two
patched crates until their fixes are released, and it has had less use on real desktops than on
Linux. [What experimental means here](#the-desktop-app-what-experimental-means).

Release builds are for **FreeBSD 14 and 15 on amd64**, built on FreeBSD 14.5. Other
architectures build from source.

![The desktop app on FreeBSD 14.5: two panes, a README.md rendered in the preview pane, the F-key bar](../screenshots/freebsd-gui.png)
*The desktop app on FreeBSD 14.5, theme Cyber, with a Markdown file in the preview pane (F3).*

## Contents

- [Install with one line](#install-with-one-line)
- [What the script does](#what-the-script-does)
- [Install by hand](#install-by-hand)
- [The packages, and what each is for](#the-packages-and-what-each-is-for)
- [Starting the apps](#starting-the-apps)
- [The search helper](#the-search-helper)
- [Search by meaning and Ask](#search-by-meaning-and-ask)
- [ZFS, packages, flags, boot environments and jails](#zfs-packages-flags-boot-environments-and-jails)
- [How FreeBSD differs from Linux here](#how-freebsd-differs-from-linux-here)
- [Updating](#updating)
- [Uninstalling](#uninstalling)
- [Building from source](#building-from-source)
- [The desktop app: what experimental means](#the-desktop-app-what-experimental-means)
- [Troubleshooting](#troubleshooting)
- [Other BSDs](#other-bsds)
- [Questions](#questions)

## Install with one line

```sh
fetch -qo - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-freebsd.sh | sh
```

The script is plain `sh`, so it runs from any login shell. It asks before it does anything that
needs root, shows each `pkg install` command before it runs it, and checks every download
against its SHA-256 sum. To read it first:

```sh
fetch https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-freebsd.sh
less install-freebsd.sh
sh install-freebsd.sh
```

| Option | Does |
|---|---|
| `--terminal-only` | Only the terminal app; no packages are needed |
| `--prefix DIR` | Install into `DIR`. Without it the script uses the place Coxswain is already in, or asks: `/usr/local` for every user, or `~/.local` for you alone |
| `--version v1.43.0` | That release instead of the latest |
| `--from DIR` | Install from release archives already in `DIR`, without downloading (a machine without network) |
| `--yes` | Answer yes to every question |
| `--uninstall` | Remove what the script installed |

Options go after `sh -s --` when the script comes through a pipe:
`fetch -qo - …/install-freebsd.sh | sh -s -- --terminal-only`.

## What the script does

1. Asks GitHub for the latest release and downloads
   `coxswain-terminal-<version>-x86_64-unknown-freebsd.tar.gz` and its `.sha256`, and stops if
   the sum does not match.
2. Installs `bin/coxswain`, the `cox` link and the manual page `coxswain(1)` under the prefix.
   With the prefix `/usr/local` it also installs the rc.d script
   `/usr/local/etc/rc.d/coxswain_index`, which stays off until you turn it on
   ([the search helper](#the-search-helper)).
3. For the desktop app, checks which of its packages are missing, prints the `pkg install`
   line, and runs it through `doas` or `sudo` when you say yes. Without WebKitGTK it leaves the
   desktop app out and says so; the terminal app is installed either way.
4. Downloads `coxswain-desktop-<version>-x86_64-unknown-freebsd.tar.gz` the same way and
   installs `bin/coxswain-gui`, `share/applications/coxswain.desktop` and the icon
   `share/icons/hicolor/128x128/apps/coxswain.png`, so Coxswain appears in your desktop's menu.
5. Lists the optional packages that are not installed, with what each adds.

When you install into `~/.local`, nothing needs root except the packages, and
`man coxswain` finds the manual once `~/.local/bin` is on your `PATH` (man(1) looks next to each
`bin` folder on it). The script prints the line to add for `sh` and for `csh`/`tcsh`.

## Install by hand

Every release on the [releases page](https://github.com/mwo-dk/coxswain/releases/latest) has
both archives with their sums:

```sh
v=v1.43.0
t=x86_64-unknown-freebsd
fetch https://github.com/mwo-dk/coxswain/releases/download/$v/coxswain-terminal-$v-$t.tar.gz
fetch https://github.com/mwo-dk/coxswain/releases/download/$v/coxswain-terminal-$v-$t.tar.gz.sha256
sha256 -c "$(cut -d' ' -f1 coxswain-terminal-$v-$t.tar.gz.sha256)" coxswain-terminal-$v-$t.tar.gz
tar xzf coxswain-terminal-$v-$t.tar.gz
cd coxswain-terminal-$v-$t
doas install -m 755 coxswain /usr/local/bin/
doas ln -sf coxswain /usr/local/bin/cox
gzip -9c coxswain.1 | doas tee /usr/local/share/man/man1/coxswain.1.gz >/dev/null
doas install -m 555 coxswain_index /usr/local/etc/rc.d/
```

The desktop archive holds `coxswain-gui`, `coxswain.desktop` and `coxswain.png`: install the
packages below first, then copy the binary to `/usr/local/bin`, the `.desktop` file to
`/usr/local/share/applications` and the icon to `/usr/local/share/icons/hicolor/128x128/apps`.
Every download can also be checked against the release's `SHA256SUMS` and its signed provenance
([Security](../reference/security.md)).

## The packages, and what each is for

The terminal app needs no packages: it links only against the base system's libraries.

| Package | For | Needed by |
|---|---|---|
| `webkit2-gtk_41` | The desktop app's window content: WebKitGTK with the 4.1 API | Desktop app, required |
| `gtk3` | The window, its menus and dialogs | Desktop app, required (comes with `webkit2-gtk_41`) |
| `libsoup3` | WebKitGTK's network layer | Desktop app, required (comes with `webkit2-gtk_41`) |
| `xdg-utils` | `xdg-open`, which opens a file in its program (**Enter** on a file the app does not show itself) | Desktop app; the terminal app uses it for the same |
| `gstreamer1-plugins-good` | Video and sound in the preview pane | Desktop app; without it a notice says what to install |
| `nerd-fonts` | The file icons and git glyphs in both apps | Optional; or set `glyphs = "ascii"` ([Glyphs and fonts](../customise/glyphs-and-fonts.md)) |
| `noto-sans-jp`, `noto-sans-kr` | Japanese and Korean letters in the desktop app | Optional; a notice says so when the language is in use and no font is there |
| `tesseract` | Search the words in scans, screenshots and pictures | Optional ([Scans and pictures](../search/scans.md)) |
| `poppler-utils` | The same for scanned PDFs: `pdftoppm` makes pictures of their pages | Optional, with `tesseract` |
| `libreoffice` | Search older Office files: `.doc`, `.ppt`, Visio and others | Optional |
| `ffmpeg` | Videos and sound the player cannot play, video thumbnails and facts, HEIC photos, [Convert video or audio](../files/convert-media.md) | Optional; containers do not run here, so this is the way |
| `ImageMagick7` | GIMP and RAW photos in the preview, [Convert or edit pictures](../files/edit-pictures.md) | Optional; the same |
| `gdal` | Maps and facts of GeoPackage, shapefile, GeoJSON, KML and GeoTIFF files, [Convert geodata](../previews/geodata.md#convert-geodata) | Optional; the same |
| `openscad` | Pictures of OpenSCAD models, [Export 3D model](../previews/openscad.md#export-3d-model) | Optional; the same |
| `kicad` | KiCad schematics and boards in the preview, [Export from KiCad](../previews/kicad.md#export-from-kicad) | Optional; the same |
| `git` | Git status, history and branches in the panels | Optional; most machines have it |
| `ollama` | A model server for search by meaning and Ask | Optional ([below](#search-by-meaning-and-ask)) |
| `rubygem-asciidoctor-pdf` | [Build PDF of AsciiDoc](../files/asciidoc-pdf.md): the containers other systems can use do not run here | Optional |

Where one of the optional programs is missing, both apps show the line that installs it with
`pkg` (`pkg install tesseract`, `pkg install texlive-full` for LaTeX previews, `pkg install
hs-pandoc` …), with **Copy** in the desktop app and **Space** to copy in the terminal app's
Settings. Coxswain never runs it; run it as root, or with `doas` in front
([Installing what is missing](../search/scans.md#installing-what-is-missing)).

The session D-Bus is not needed. A desktop session that runs `dbus` (as KDE Plasma, Xfce, GNOME
and MATE do) is fine too.

## Starting the apps

| App | Start | Notes |
|---|---|---|
| Terminal app | `coxswain` or `cox`, optionally with two folders: `coxswain ~/src /usr/ports` | Any terminal with 256 colours; true colour looks best. Works on the console (`vt`) too, with `glyphs = "ascii"` |
| Desktop app | `coxswain-gui`, or *Coxswain* in the desktop's menu | Needs an X11 or Wayland session |

`coxswain --help` lists the command-line flags, and `man coxswain` describes them.

## The search helper

Find reads names, words and meaning from an index that the search helper keeps current. By
default the helper starts with the first Coxswain app and leaves ten minutes after the last
([The search helper](../search/helper.md)). To have it read while no app is open, start it with
your session, from boot, or from your login shell. Only one helper runs per user at a time, so
having two of these does no harm.

### With your desktop session

*Settings → Finding files → Details → Background reading → Start with my session* in the desktop app,
or `coxswain --index-service on` in a terminal, writes an XDG autostart entry:

```
~/.config/autostart/coxswain-index.desktop
```

KDE Plasma, Xfce, GNOME, MATE, LXQt and Cinnamon start it at login. A window manager on its own
(i3, sway, Openbox, twm) does not read autostart entries: use one of the ways below. The entry
starts the helper now as well. `coxswain --index-service off` (or unticking it) removes the
entry; the helper running now stays until you log out.

### From boot, with rc.d

For a machine you use over SSH, or a window manager without autostart. The script installs
`/usr/local/etc/rc.d/coxswain_index` (with the prefix `/usr/local`); it runs the helper as the
user you name, under daemon(8), which starts it again if it ends:

```sh
doas sysrc coxswain_index_enable=YES coxswain_index_user=alice
doas service coxswain_index start
service coxswain_index status
```

| rc.conf variable | Default | Meaning |
|---|---|---|
| `coxswain_index_enable` | `NO` | Start it at boot |
| `coxswain_index_user` | none, required | The user whose files are indexed; the helper runs as this user, with this user's home |

What the helper says goes to syslog (`/var/log/messages`), tagged `coxswain_index`. One rc.d
script serves one user; for a second user, copy it under another name
(`coxswain_index_bob`, with `name=` changed to match).

### From your login shell

The smallest way, for one user: start it when you log in. For `sh` (the default since FreeBSD
14), in `~/.profile`:

```sh
coxswain --index-helper --stay >/dev/null 2>&1 &
```

For `csh` or `tcsh`, in `~/.login`:

```csh
( coxswain --index-helper --stay >& /dev/null & )
```

A second login finds the first helper running and its own one ends at once.

## Search by meaning and Ask

| Way | On FreeBSD |
|---|---|
| The built-in model | Works as on Linux, on the processor: `coxswain --meaning on`, or *Settings → Search by meaning*. The model (465 MB) is downloaded once, after you say so |
| Ollama on this machine | `doas pkg install ollama`, start it with `ollama serve` in a terminal of its own, then `coxswain --meaning ollama` or the guide in Settings |
| A server elsewhere | Lemonade, LM Studio or llama.cpp on another machine, with the OpenAI API: `coxswain --meaning server http://host:port MODEL`. Its address is shown in Settings, and the text of your files goes there |

**Graphics cards.** The setup guide (`coxswain --setup-search`, or *Set up…* in Settings) finds an
NVIDIA card through `nvidia-smi`, which the `nvidia-driver` package installs. AMD cards and NPUs
are found on Linux from files FreeBSD does not have, so on FreeBSD the guide says no card was
found and advises models that suit the processor. Whether Ollama uses a card depends on how its
package was built: after the guide's test question, `ollama ps` shows `100% GPU` or `100% CPU`.

## ZFS, packages, flags, boot environments and jails

What a FreeBSD machine has that others do not, Coxswain shows where you are already looking.
Everything here only reads, except your own file flags, and needs no root.

| What | Where | How |
|---|---|---|
| ZFS snapshots | **Alt+Z** on a folder: its dataset's snapshots, newest first, each a read-only folder as it was | [ZFS snapshots as folders](../files/zfs-snapshots.md) |
| The dataset | The pane's footer (the panel's bottom border in the terminal app): `zroot/home/alice · 1.52x · 12.3 GB used · 88.1 GB free`, or `… of 100 GB` with a quota | `zfs get`, kept ten seconds a dataset |
| ZFS facts | **Alt+Enter** (Properties): dataset, mountpoint, compression and ratio, used, available, referenced, quota and refquota, how many snapshots | [Properties](../files/properties.md#zfs-packages-and-file-flags) |
| The package of a file | **Alt+Enter** on a file under `/usr/local`: *Package git-2.56.0* | `pkg which` |
| A package's files | *F9 → Files of this package*, or the button in Properties: `<file>/@package` lists every file it installed. Offered for files outside your home folder, the temporary folders (`/tmp`, `/var/tmp`) and `/mnt` and `/media`, where pkg installs nothing | `pkg info -l` |
| File flags | **Alt+Enter**: `uarch`, `nodump`, `schg` … as `ls -lo` names them; tick `nodump`, `hidden`, `uchg`, `uappnd` on your own files (on ZFS only `nodump` and `hidden`) | stat(2), chflags(2) |
| Boot environments | The desktop app's sidebar, and **Alt+F1** / **Alt+F2** in the terminal app | `bectl list -H` |
| Jails | The same places | `jls -h jid name path host.hostname` |

### Boot environments and jails

<!-- screenshot: freebsd-sidebar-be.png: the desktop app (Cyber) on FreeBSD with a ZFS root: the sidebar's Boot environments section (default running now and on reboot, 14.1-backup not mounted, greyed) and Jails (web jail 1, web.example.org) -->

With a ZFS root, the desktop app's sidebar has a section *Boot environments*: each one by
name, with *running now*, *active on reboot*, *running now and on reboot* or *not mounted*
after it. One that is mounted (the running one at `/`, another after `bectl mount`) opens as a
folder; a click on one that is not mounted says *The boot environment … is not mounted: bectl
mount … mounts it, as root*, and changes nothing. Below it, *Jails*: each running jail by name,
with its jid and host name; a click opens its root folder when you may read it.

In the terminal app, **Alt+F1** (left panel) and **Alt+F2** (right panel) list the same, as
Norton Commander's drive menu did, under a first line *Type a path…* that opens the usual
go-to line. Type to filter, **Enter** to go. On a machine without boot environments or jails
(and off FreeBSD) **Alt+F1** goes straight to the go-to line, as before.

Coxswain never activates, mounts, destroys or starts anything: `bectl activate`, `bectl
mount`, `service jail start` stay yours. Both lists are read when the app starts (the desktop
app) or when **Alt+F1** is pressed (the terminal app); `bectl` needs a ZFS root, and without one
the section is left out.

### Questions about these

#### Does the snapshot list need root, or `zfs allow`?

No: `zfs list -t snapshot` and reading
`.zfs/snapshot` work for every user ([more](../files/zfs-snapshots.md#do-i-need-root-or-zfs-allow)).

#### Why is a boot environment greyed?

It is not mounted, so there is no folder to open.
`doas bectl mount 14.1-backup` mounts it under `/tmp`; it then opens like any other.

#### Why does every file show `uarch` under Flags?

ZFS sets the archive flag on files it writes;
`ls -lo` shows it too ([more](../files/properties.md#why-does-every-file-on-zfs-show-uarch)).

#### Can I clear `schg` from Coxswain?

No: system flags are root's, and at securelevel 1 or higher
not even root can clear them until the machine runs at securelevel 0. Properties says so when
one is set.

#### Why is there no *Package* line?

The file belongs to no package: it is part of the base
system (`/bin`, `/usr/bin`, `/etc`, kept by `freebsd-update`), yours, or in a tree such as
`/usr/ports`. With pkgbase, base system files belong to `FreeBSD-*` packages and show them. A
port you built and installed is a package like any other.

## How FreeBSD differs from Linux here

| Feature | On FreeBSD |
|---|---|
| File watching | kqueue. It holds an open descriptor for every path it watches, so the helper watches folders only, not files, shallowest first and at most 20,000 of them (a FreeBSD base system with a desktop has about 11,000), and never more than three quarters of its open-file limit (`ulimit -n`, raised to the hard limit first). New files and folders in a watched folder open no descriptors of their own. A folder made after the helper started is watched as soon as it appears, with the folders in it, within the same 20,000. A file added, removed or renamed shows in Find within a second; folders past the 20,000 are read again at the hourly rebuild, and changed text is read within ten minutes |
| Trash (F8) | `~/.local/share/Trash`, the freedesktop.org layout that KDE, Xfce and GNOME use, so their trash shows and restores what Coxswain moved there |
| Drives in the sidebar | The mounted file systems, from the kernel's mount list (getmntinfo(3)); the root file system is *System*. Free space is what `df` shows as *Avail* |
| Battery | `sysctl hw.acpi.acline`: `0` means on battery, and the helper pauses ([Battery](../search/battery.md)). A machine without ACPI power reporting counts as on mains |
| Memory in the setup guide | `sysconf(_SC_PHYS_PAGES)` |
| Removable disks | Known by their path only: a USB disk mounted somewhere else next time is read again, not recognised ([Removable disks](../search/removable-disks.md)) |
| Start with my session | An XDG autostart entry, not a service ([above](#the-search-helper)) |
| The update notice | Names the install script's one-line command ([Updating](#updating)) |
| Cloud folders | No cloud clients are detected on FreeBSD; files under a FUSE mount are read like any other |
| ZFS | The dataset of a folder from statfs(2) (Linux reads `/proc/self/mountinfo`); snapshots, the footer and Properties work the same with OpenZFS on Linux and macOS |
| File flags | chflags(2), shown and set for your own files; Linux shows `lsattr`'s immutable, append-only and no-dump attributes, read-only |
| Packages, boot environments, jails | FreeBSD only: `pkg`, `bectl`, `jls` |

## Updating

Both apps check for a newer release when they start, then once a day while open, and say so with the command to update
([Update checks](../reference/updates.md)). On FreeBSD that command is the install line again:

```sh
fetch -qo - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-freebsd.sh | sh
```

It finds where Coxswain is installed and replaces it there. Your settings and the index stay.

## Uninstalling

```sh
fetch -qo - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-freebsd.sh | sh -s -- --uninstall
```

This removes the programs, the manual page, the menu entry, the icon, the rc.d script and the
autostart entry. If rc.conf turns the helper on, remove those lines too:
`doas sysrc -x coxswain_index_enable coxswain_index_user`. Your settings, the state and the index
stay; remove them with `rm -rf ~/.config/coxswain ~/.local/share/coxswain ~/.cache/coxswain`
([Where things are kept](../reference/where-things-are-kept.md)).

## Building from source

On any architecture FreeBSD's Rust supports (aarch64 too):

```sh
doas pkg install git rust pkgconf
git clone https://github.com/mwo-dk/coxswain.git && cd coxswain
cargo build --release --locked -p coxswain
```

For the desktop app as well:

```sh
doas pkg install node22 npm-node22 webkit2-gtk_41 gtk3 libsoup3 librsvg2-rust
(cd gui && npm ci && npm run build)
cargo build --release --locked -p coxswain-gui
```

The binaries are in `target/release/`. The terminal app is also on crates.io:
`cargo install --locked coxswain`. (`install/install.sh` is the Linux and macOS script; it needs
bash and does not know `pkg`.)

To try a change on FreeBSD, OpenBSD, NetBSD or OmniOS without one of those machines,
`tools/vms/` in the source makes a virtual machine of each from its official image, and
`tools/vms/test-in.sh freebsd` runs a checkout's tests in it
([tools/vms/README.md](../../tools/vms/README.md)).

## The desktop app: what experimental means

Coxswain's desktop app is a [Tauri](https://tauri.app) app, and Tauri does not support FreeBSD
officially. It builds and runs because its window layer (tao, wry) is written for GTK on the
BSDs as on Linux, with one gap that Coxswain patches until an upstream release closes it:

| Crate | The problem | Patched with | Upstream |
|---|---|---|---|
| `tao` 0.37.1 | Resize hit testing was compiled for Linux only, so tao did not build on FreeBSD | tao's own commit `d19f4c1`, merged after 0.37.1 | [tauri-apps/tao#1356](https://github.com/tauri-apps/tao/pull/1356) |

The patch only widens a `cfg(target_os = "linux")` to the BSDs, so the Linux, macOS and Windows
builds compile the same code as from crates.io. It is in `[patch.crates-io]` in `Cargo.toml`
and goes when the fixed version is released. Dragging files out of the window uses GTK itself,
as on Linux.

Tested on FreeBSD 14.5 (amd64), on every change in CI and by hand under X11:

| Works | |
|---|---|
| Browsing, tabs, the sidebar with places and drives, the F-key bar, F9's command list | Yes |
| The preview pane (Markdown, code, pictures, PDF and the rest that need no extra package) | Yes |
| Find: names, words in files, the search helper | Yes |
| Copy (F5), move (F6), new folder (F7), delete to the trash (F8) | Yes |
| The clipboard: **Ctrl+C** on files offers them as `file://` lists (`text/uri-list`, GNOME's and Nautilus's formats) as on Linux, and **Ctrl+V** pastes them | Yes |
| Dragging files out of the window | The same GTK code as on Linux, where drops on other programs are tested (X11 and Wayland); not yet confirmed on a FreeBSD desktop |
| Opening a file in its program | Through `xdg-open` (package `xdg-utils`), the same code as on Linux; not tried on FreeBSD yet |
| Video and sound in the preview | With `gstreamer1-plugins-good` |
| Wayland sessions | Not tested yet; `GDK_BACKEND=x11` starts it under XWayland |
| FreeBSD 15 | Built on 14.5; tests and the port run on 15.1 in CI too, and tried by hand (below) |

FreeBSD 15.1 (amd64) was tried by hand on 2026-10-16, both apps of 2.24.1 under Xfce with
X11 (`scfb`), installed with the one-line install script:

| Tried | |
|---|---|
| The first-run guide, browsing, tabs, the sidebar, F1, F9's command list, the action menu (**Shift+F10**) | Work in both apps |
| Previews: Markdown, PDF, pictures; a `.zip` opened as a folder and a file in it previewed | Work |
| Copy (F5), new folder (F7), delete to the trash (F8), **Ctrl+Z** | Work. Fixed since: folder sizes on screen stayed as they were before the operation until a restart, and after undoing a delete the cursor did not go to what came back |
| **Enter** on a file opens it in its program | Works, through `xdg-open` |
| Find: words in files, names, the search helper | Work. Fixed since: names in a folder made after the helper started were not found until its hourly rebuild; a name that is the whole query, and your home folder, now come before the system's headers |
| Settings | Work. Fixed since: the heading *How far should Find look?* was squeezed to a word a line; *Previews* now says that podman and docker do not run its Linux images here and names `pkg install texlive-full`; *Never indexed* no longer lists Linux's `/sys` and `/run` |
| The sidebar's free space | Fixed since: it showed 18.9 GB where `df` showed 26 GB free (it counted free inodes, not free blocks) |
| Properties | Works. Fixed since: *Owner* shows the names (`mwo:wheel`), not only the ids; *Files of this package* is no longer offered for files in `/tmp` |
| `coxswain-gui` over ssh | Fixed since: it ended with a GTK panic; now it says there is no display and exits with status 1. `coxswain-gui --version` and `--help` work without one |

The app has no tray icon and sends no desktop notifications, so neither depends on FreeBSD
support. Please report what works and what does not on your desktop in an
[issue](https://github.com/mwo-dk/coxswain/issues): the word *experimental* goes when it has had
that use.

## Troubleshooting

#### The icons are empty boxes

No Nerd Font is installed. `doas pkg install nerd-fonts`, then
restart the app; or choose plain characters: the [first-run guide](../panels/first-run.md)'s
*Looks* step offers both (*Use plain characters*), or Settings (**Ctrl+,**; **F12** in the terminal app) → *Looks* → *Icons
and git glyphs* → *Plain characters (ASCII)*, or `glyphs = "ascii"`
in `config.toml` ([Glyphs and fonts](../customise/glyphs-and-fonts.md)).

#### `coxswain-gui` says it cannot find `libwebkit2gtk-4.1.so.0`

WebKitGTK is not installed:
`doas pkg install webkit2-gtk_41`.

#### MESA-EGL warns about DRI3 when the app starts

Harmless: there is no accelerated OpenGL
(a virtual machine, or `Xvfb`), and WebKitGTK draws in software.

#### The window stays white or flickers

Some graphics drivers disagree with WebKitGTK's
compositing. Start it with `WEBKIT_DISABLE_COMPOSITING_MODE=1 coxswain-gui`; if that helps,
put the variable in the `Exec=` line of `coxswain.desktop`, or in your shell's profile.

#### Wayland or X11?

GTK chooses Wayland when `WAYLAND_DISPLAY` is set and X11 otherwise. To try
X11 under a Wayland compositor: `GDK_BACKEND=x11 coxswain-gui`.

#### Enter on a file says no program could open it

`xdg-open` is missing (`doas pkg install
xdg-utils`), or no program is set for that kind of file: `xdg-mime default <app>.desktop
<type>`.

#### A new file deep in a large tree shows in Find only after an hour

Its folder is past the
20,000 the helper watches ([above](#how-freebsd-differs-from-linux-here)). Leave large trees you
never search out of the index (`/usr/ports`, `/usr/src`, build folders): *Settings → Finding
files → Details → Folders → Never indexed*, or `name_exclude` in `[search]` ([Choosing the folders](../search/folders.md)).

## Other BSDs

NetBSD, OpenBSD and illumos have pages of their own, with their install line, their service
for the search helper and what differs there. DragonFly BSD: not supported; its Rust (1.85 in DPorts) is too old for Coxswain's dependencies.

| System | Terminal app | Desktop app | Page |
|---|---|---|---|
| NetBSD | Release builds, tested in CI | See its page | [NetBSD](netbsd.md) |
| OpenBSD 7.9 | Release builds, tested in CI with OpenBSD's own Rust | Experimental | [OpenBSD](openbsd.md) |
| DragonFly BSD | Not supported; its Rust (1.85 in DPorts) is too old for Coxswain's dependencies | Not supported | |
| illumos (OmniOS, OpenIndiana) | Release builds, tested in CI with ZFS | Not built | [illumos](illumos.md) |
| TrueNAS CORE | This page's build, `--terminal-only`, into your home | Not on a NAS | [TrueNAS](truenas.md) |

## Questions

#### Is the desktop app safe to use on FreeBSD?

It uses the same code as on Linux for everything
that touches your files: copying, moving and deleting are in the shared core, tested on FreeBSD
in CI. *Experimental* is about the window layer and desktop integration, not about your data.

#### Why is the desktop app experimental and the terminal app not?

The terminal app depends on
nothing FreeBSD-specific beyond what its tests cover. The desktop app depends on Tauri, which
does not support FreeBSD officially and needs two patched crates
([above](#the-desktop-app-what-experimental-means)).

#### Is there a port or a package?

Not yet in the ports tree. A `sysutils/coxswain` port of the
terminal app is ready in [packaging/freebsd](../../packaging/freebsd/README.md) and waits for
review; until it is in, the script, the archives or `cargo install --locked coxswain`.

#### Does it need Linux binary compatibility (`linux64`)?

No. Both apps are native FreeBSD
binaries.

#### Why does the script ask for root?

Only to install packages with `pkg`, and to write under
`/usr/local` when you choose it. With `--prefix ~/.local` and `--terminal-only`, it needs no
root at all.

#### Does Start with my session work under i3 or another window manager?

Not by itself: only
desktop environments read XDG autostart entries. Use the [rc.d script](#from-boot-with-rcd) or
the [login shell line](#from-your-login-shell); or start the entry with `dex`, if you use it
already.

#### Does it run on aarch64 (a Raspberry Pi, an Ampere server)?

From source, yes; there is no
release build yet ([Building from source](#building-from-source)).

---
[← Previous: Systems](README.md) · [Next: NetBSD →](netbsd.md)