Linux Support

PortBay's Linux desktop target is Ubuntu 22.04 and Ubuntu 24.04 first. Fedora and Debian are best-effort until their DNS and certificate paths are verified in the QA matrix.

Packages

Install the desktop and runtime dependencies before building from source:

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

Release deb packages declare the runtime equivalents of these dependencies. AppImage builds still expect dnsmasq, polkit, and a working systemd-resolved setup on the host.

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.

Known Limitations

• 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 supported by the Tauri updater channel. deb updates are expected to flow through the system package manager.
• 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.
• The single-instance plugin may require xdotool on X11; Wayland focus-stealing restrictions can prevent second-launch focus.

Local Build

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