Install

PortBay ships as a signed, notarized macOS app for both Apple Silicon (M-series) and Intel, and as a signed Linux x86_64 AppImage, deb or rpm. All three are published on the same release at the same version.

Linux needs glibc 2.38 or newer (Ubuntu 24.04, Debian 13, Fedora 39+); see Linux Support for the package files, signature verification, and the limitations that apply there.

Homebrew

brew tap portbay-app/portbay
brew install --cask portbay

The cask installs PortBay.app and the bundled portbay CLI. Uninstalling with Homebrew removes the app; brew uninstall --zap portbay also removes PortBay's local app data, caches, logs, preferences, and WebKit state.

DMG

Download the latest PortBay-<version>.dmg from GitHub Releases, mount it, and drag PortBay.app into Applications. The app is signed and notarized for macOS Gatekeeper.

Build From Source

Source builds are for contributors. The app expects Node, pnpm, Rust, and Tauri prerequisites to be installed.

Requirements

Requirement	Notes
macOS	Apple Silicon (arm64) only, macOS 11+. Signed DMG and Homebrew cask.
Linux	x86_64, glibc 2.38+ (Ubuntu 24.04, Debian 13, Fedora 39+). Download the signed AppImage, deb or rpm from the releases page; the apt/dnf repository is not published yet. A source build requires WebKitGTK, GTK, libayatana-appindicator, libsecret/D-Bus, dnsmasq, polkit, and systemd-resolved for full DNS support. See Linux Support.
Node.js	Use the project’s supported local Node version.
pnpm	The repo uses pnpm-lock.yaml.
Rust	Required for the Tauri core and CLI.
Xcode Command Line Tools	Required for native builds on macOS.

Clone And Install

git clone https://github.com/portbay-app/portbay.git
cd portbay
pnpm install

Fetch Development Sidecars

Tauri looks for sidecars under src-tauri/binaries/<name>-<target-triple>. Process Compose is committed. The larger or platform-specific tools are fetched per checkout.

./scripts/fetch-caddy.sh
./scripts/fetch-mkcert.sh
./scripts/fetch-mailpit.sh
./scripts/fetch-cloudflared.sh
./scripts/fetch-dnsmasq.sh

The scripts write into the repository checkout. They should be run from the repo root. Do not hand-place global binaries into the app bundle while developing; the app should be able to reproduce its own expected local sidecar layout.

On macOS, fetch-dnsmasq.sh bundles the DNS resolver that powers wildcard *.test routing, so there is no separate brew install dnsmasq step. On Linux, the script writes a small wrapper that calls the system dnsmasq; install the distro package before running the app.

Verify The Checkout

cd src-tauri
cargo test
cd ..
pnpm check

Run The App

pnpm tauri dev

If the app fails before the first window opens, check that the sidecars are present and executable.