Skip to content
Peppy

Installation

To install peppy, run the following command in your terminal:

Terminal window
curl -fsSL https://peppy.bot/install.sh | sh

The installer supports Ubuntu 24.04 or later and the Linux distributions built on it, Debian 13 or later (x86_64 and aarch64, tested on Ubuntu 24.04), Raspberry Pi OS (see Raspberry Pi), and macOS on Apple Silicon. It recognises an Ubuntu-based distribution by ID or ID_LIKE in /etc/os-release, and Debian by ID=debian alone: a distribution that names Debian in ID_LIKE only, such as Devuan, is not supported.

On Linux, Peppy needs a 64-bit system with glibc 2.38 or later. The installer reads the architecture of the packages with dpkg --print-architecture, because a 64-bit kernel can run a 32-bit system, and the glibc version with getconf GNU_LIBC_VERSION. It reads the glibc and not the release number, because a distribution built on Ubuntu numbers its releases its own way: Linux Mint 21, for example, is built on Ubuntu 22.04. On a 32-bit system, on an older glibc (glibc 2.35 on Ubuntu 22.04 and the distributions built on it, 2.36 on Debian 12), and on any other system, Fedora and Arch Linux among them, the installer stops with an error before it changes anything.

This installer also sets up the peppy background service and populates the repository index that name-based launches resolve from. To skip that step, set PEPPY_NO_SERVICE_INSTALL=1. The flag skips the repository setup along with the service, so a launch by name then fails with nodes.json5 not found or empty until you run peppy repo init and peppy repo update yourself.

The installer can also unpack a release archive you already have, instead of downloading one:

Terminal window
curl -fsSL https://peppy.bot/install.sh | sh -s -- ./peppy-x86_64-unknown-linux-gnu.tgz

If a daemon is already running, the installer asks for confirmation before replacing it; set PEPPY_FORCE_REINSTALL=1 for non-interactive installs.

Each Peppy version reads the content of the default repositories that was released with it (see Repositories). Installing another Peppy version therefore also changes the hub content those repositories read, and the daemon reads it again at its next start.

Raspberry Pi

Section titled “Raspberry Pi”

Of the Raspberry Pi boards, the installer supports those built on the BCM2712 SoC: the Raspberry Pi 5, the Raspberry Pi 500 and the Compute Module 5. It recognises a Raspberry Pi board by a raspberrypi, entry in the compatible list of the device tree (/sys/firmware/devicetree/base), and the BCM2712 by brcm,bcm2712 in the same list. The rule holds whatever the distribution: on an older board, such as the Raspberry Pi 4 or the Raspberry Pi 3, the installer stops with an error that names the board, on Raspberry Pi OS, Ubuntu and Debian alike.

On these boards, the installer supports Raspberry Pi OS (64-bit) based on Debian 13 (trixie) or later, and the other distributions above. It recognises Raspberry Pi OS by the /etc/rpi-issue file of its image, and stops with an error before it changes anything on:

  • Raspberry Pi OS where the device tree names no board. Raspberry Pi OS runs on Raspberry Pi boards only.
  • the 32-bit Raspberry Pi OS. On a Raspberry Pi 5 it also runs a 64-bit kernel, and its packages are armhf, not arm64.
  • Raspberry Pi OS based on Debian 12 (bookworm), the release Raspberry Pi Imager lists as Legacy. Its glibc (2.36) is older than the 2.38 that Peppy needs.

To install Raspberry Pi OS (64-bit), use Raspberry Pi Imager.

Installer environment variables

Section titled “Installer environment variables”
VariableEffect
PEPPY_VERSIONVersion to install (default: latest)
PEPPY_HOMEInstall prefix (default: ~/.peppy)
PEPPY_BIN_DIRBinary install directory (default: $PEPPY_HOME/bin)
PEPPY_REPOURLBase URL for downloads (default: https://peppy.bot)
PEPPY_DOWNLOAD_URLOverride the full download URL
PEPPY_NO_PATH_UPDATEIf set, do not update the shell PATH config
PEPPY_FORCE_REINSTALLIf set, skip the confirmation prompt when a daemon is running
PEPPY_NO_ROOT_INSTALLIf set, never use sudo; missing dependencies become hard errors and Apptainer setup is deferred to peppy container setup
PEPPY_NO_SERVICE_INSTALLIf set, skip the service install and the repository init/refresh
PEPPY_NO_CONTAINER_SETUPIf set, skip the Apptainer container setup (useful inside Docker/Podman)

Verifying the installation

Section titled “Verifying the installation”

The service installs at user level by default; run peppy service install with sudo for a system-wide install. The snippets below assume the default user-level install. You can verify the service is running with:

Terminal window
systemctl --user status peppy
Managing the service (optional)

peppy ships its own platform-independent service commands, which are what the installer itself runs:

Terminal window
peppy service install     # install the background service
peppy service stop        # stop it
peppy service uninstall   # remove it

To drive the service through the platform’s own service manager instead:

Start the service:

Terminal window
systemctl --user start peppy

Stop the service:

Terminal window
systemctl --user stop peppy

Restart the service:

Terminal window
systemctl --user restart peppy