Linux Support

Linux ships from v0.1.9

Download it from the releases page. Three formats are published for x86_64, each with a detached GPG signature you can verify against the key in docs/portbay-linux-signing-key.asc:

Format	File
AppImage	PortBay_<version>_amd64.AppImage (+ .asc)
Debian / Ubuntu	PortBay_<version>_amd64.deb (+ .asc)
Fedora / RHEL	PortBay-<version>-1.x86_64.rpm (+ .asc)

Requires glibc 2.38 or newer — Ubuntu 24.04, Debian 13, Fedora 39 and later. This floor comes from the bundled ONNX Runtime, which references __isoc23_* symbols; on an older glibc the app will not start. Ubuntu 22.04 and Debian 12 are below that line.

Only x86_64 is published. ARM64 Linux still needs a source build.

The apt/dnf repository is not published yet

docs/linux-install.md describes an apt/dnf repository at portbay-app.github.io/portbay. That repository does not exist — it shares a GitHub Pages destination with this documentation site, so publishing it would replace these docs. Install from the release files above instead.

What this page IS: the Linux design of record — the package targets the build scripts already produce locally, the DNS and privileged-helper strategy the Linux code paths implement, and the limitations that will apply on the day a Linux artifact ships. Ubuntu 22.04/24.04 and Debian 12 are the intended build baseline; Fedora/RHEL and Arch/Manjaro are intended package targets.

Package Formats (planned — none published)

None of these are downloadable. Status describes what the build scripts produce on a developer's own machine, not what a release contains.

Format	Distros	Status
AppImage	Most x86_64 desktop distros	Planned universal release artifact and updater target. Built locally by scripts/release-appimage-local.sh; never published.
deb	Debian / Ubuntu	Planned native package with runtime dependencies declared. Built locally by scripts/release-linux-local.sh; never published.
rpm	Fedora / RHEL-compatible distros	Planned native package with runtime dependencies declared. Built locally by scripts/release-linux-local.sh; never published.
Snap	Ubuntu, Debian, and Snap-enabled distros	Planned classic-confinement package built from the release deb. Nothing is published to the Snap Store.
AUR	Arch Linux / Manjaro	Planned portbay-bin package that extracts the release deb. Nothing is published to the AUR.

Build Dependencies

Building from source is the only way to run PortBay on Linux today. Install the desktop and runtime dependencies first, on Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  libdbus-1-dev \
  libsecret-1-dev \
  dnsmasq \
  libnotify-bin \
  policykit-1 \
  rpm

On Fedora/RHEL-family systems, install the equivalent packages:

sudo dnf install -y \
  webkit2gtk4.1-devel \
  gtk3-devel \
  libayatana-appindicator-gtk3-devel \
  librsvg2-devel \
  dbus-devel \
  libsecret-devel \
  dnsmasq \
  libnotify \
  polkit \
  rpm-build

On Arch Linux / Manjaro:

sudo pacman -S --needed \
  webkit2gtk-4.1 \
  gtk3 \
  libayatana-appindicator \
  librsvg \
  dbus \
  libsecret \
  dnsmasq \
  libnotify \
  polkit

The planned deb/rpm/AUR packages declare the runtime equivalents of these dependencies. AppImage builds still expect dnsmasq, polkit, and a working systemd-resolved setup on the host. The Snap package uses classic confinement because PortBay needs host DNS, helper, process, and Secret Service integration.

DNS And Hosts

Linux wildcard DNS uses systemd-resolved in the first supported tier. PortBay writes a managed drop-in under:

/etc/systemd/resolved.conf.d/portbay-<suffix>.conf

The drop-in points ~<suffix> queries at PortBay's loopback dnsmasq listener. Exact project hostnames still use the privileged hosts helper as the guaranteed fallback.

Privileged Helper

The Linux helper is installed with a polkit prompt and registered as a systemd service. It listens on the same Unix socket as macOS:

/var/run/portbay-hosts-helper.sock

The helper checks the connecting process UID with Linux SO_PEERCRED and only accepts the installing user or root.

Certificate Trust

Install CA adds PortBay's local CA to the NSS store that Firefox and Chromium read (this needs certutil, from libnss3-tools / nss-tools). It needs no root and raises no prompt.

It does not add the CA to the system store. mkcert does that through sudo, and a desktop app has no terminal to answer the password prompt, so mkcert -install fails there. Tools that read the system store, such as curl, need a one-time step in a terminal. After Install CA, PortBay shows the step with a copy button and the CA's path filled in. For mkcert's default location it is:

# Debian / Ubuntu
sudo cp ~/.local/share/mkcert/rootCA.pem /usr/local/share/ca-certificates/portbay-rootCA.crt
sudo update-ca-certificates

# Fedora / RHEL
sudo cp ~/.local/share/mkcert/rootCA.pem /etc/pki/ca-trust/source/anchors/portbay-rootCA.pem
sudo update-ca-trust

# Arch
sudo trust anchor --store ~/.local/share/mkcert/rootCA.pem

mkcert -CAROOT prints the directory if yours differs.

Known Limitations

These describe the first Linux release when there is one; they are not limitations of anything you can install today.

• Sandboxed Run is disabled on Linux for the first release. PortBay refuses to run a project "sandboxed" without a Linux sandbox backend.
• Wildcard DNS currently supports systemd-resolved; NetworkManager-only and resolvconf-only setups are best-effort.
• AppImage auto-update is wired to the Tauri updater channel, but the channel serves no Linux artifact today (latest.json on the current release lists macOS only). deb, rpm, Snap, and AUR updates are expected to flow through their package managers once those packages are published.
• Wayland compositors differ in transparency and tray behavior. PortBay uses an opaque Linux shell fallback instead of macOS vibrancy.
• If Secret Service is missing, auth falls back to PORTBAY_SESSION_JSON or a local ~/.config/PortBay/session.json file with 0600 permissions; sync recovery keys fall back to PORTBAY_SYNC_KEY or ~/.config/PortBay/sync.key with 0600 permissions. Treat both environment overrides as security-sensitive — anything that can read the process environment can read the tokens (see the "Session Environment Override" section of SECURITY.md); the app logs a warning whenever a session is loaded from the environment.
• The single-instance plugin may require xdotool on X11; Wayland focus-stealing restrictions can prevent second-launch focus.

Local Build

This is the supported way to run PortBay on Linux right now, and it is a contributor path: it builds an unsigned debug binary from your own checkout.

./scripts/fetch-process-compose.sh
./scripts/fetch-caddy.sh
./scripts/fetch-mkcert.sh
./scripts/fetch-mailpit.sh
./scripts/fetch-cloudflared.sh
./scripts/fetch-dnsmasq.sh
./scripts/build-hosts-helper.sh
./scripts/build-mcp.sh
pnpm tauri build --debug --no-bundle

For a local AppImage smoke build, run:

./scripts/release-appimage-local.sh

For local AppImage + deb + rpm smoke artifacts on Linux x86_64, run:

./scripts/release-linux-local.sh