Installation

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

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

The installer supports Ubuntu and the Linux distributions built on it (x86_64 and aarch64, tested on Ubuntu 24.04), and macOS on Apple Silicon. It recognises an Ubuntu-based distribution by ID or ID_LIKE in /etc/os-release. On any other system, Fedora and Arch Linux among them, it 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.

Note

To install a specific version, set the PEPPY_VERSION environment variable:

curl -fsSL https://peppy.bot/install.sh | PEPPY_VERSION="v0.20.0" sh

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

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.

Installer environment variables

Variable	Effect
PEPPY_VERSION	Version to install (default: latest)
PEPPY_HOME	Install prefix (default: ~/.peppy)
PEPPY_BIN_DIR	Binary install directory (default: $PEPPY_HOME/bin)
PEPPY_REPOURL	Base URL for downloads (default: https://peppy.bot)
PEPPY_DOWNLOAD_URL	Override the full download URL
PEPPY_NO_PATH_UPDATE	If set, do not update the shell PATH config
PEPPY_FORCE_REINSTALL	If set, skip the confirmation prompt when a daemon is running
PEPPY_NO_ROOT_INSTALL	If set, never use sudo; missing dependencies become hard errors and Apptainer setup is deferred to peppy container setup
PEPPY_NO_SERVICE_INSTALL	If set, skip the service install and the repository init/refresh
PEPPY_NO_CONTAINER_SETUP	If set, skip the Apptainer container setup (useful inside Docker/Podman)

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:

Linux

systemctl --user status peppy

macOS

launchctl list bot.peppy

Managing the service (optional)

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

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:

Linux

Start the service:

systemctl --user start peppy

Stop the service:

systemctl --user stop peppy

Restart the service:

systemctl --user restart peppy

macOS

Start the service:

launchctl load ~/Library/LaunchAgents/bot.peppy.plist

Stop the service:

launchctl unload ~/Library/LaunchAgents/bot.peppy.plist

Restart the service:

1. Unload the service:

   launchctl unload ~/Library/LaunchAgents/bot.peppy.plist

2. Reload the service:

   launchctl load ~/Library/LaunchAgents/bot.peppy.plist