Install

Install ProgressPals.

ProgressPals ships as a single Python package. Installing it gives you the pals CLI and everything needed to host or join a swarm.

Requirements

Python 3.10 or 3.11. Newer Python versions are not yet supported by the upstream tensor-parallel and hivemind dependencies.
Linux or macOS. Windows is not officially supported.
A GPU helps, not required. CUDA 12.x for NVIDIA, MPS on Apple Silicon (M1/M2/M3). CPU-only works for small models or as a contributor to a larger swarm.
Disk space. Your share of the model lives in the HuggingFace cache. A few GB for an 8B model up to tens of GB for a slice of a 405B model.

Install the CLI

We recommend installing into a virtual environment so the dependencies don’t collide with anything else on your machine.

install

$python3.11 -m venv ~/.venv/progresspals

$source ~/.venv/progresspals/bin/activate

$pip install progresspals

✓ Successfully installed progresspals

Verify the install:

verify

$pals --help

Usage: pals [OPTIONS] COMMAND [ARGS]...

GPU users: if you plan to host layers, make sure torch.cuda.is_available() returns true before running pals create. The CLI does not install CUDA drivers for you.

Initialize your config

pals init creates the local config directory and writes a default config.json. Your libp2p identity key gets generated on the first server start (pals create / pals join / pals serve). Run pals init once per machine.

pals init

$pals init

✓ config written to ~/.config/progresspals/config.json

identity.key will be created on first server start

The default config directory respects $XDG_CONFIG_HOME (Linux/macOS: ~/.config/progresspals). Override with --config-dir if you need to run multiple swarms side by side from the same machine.

Connect your ProgressPals account

Hosting a swarm and managing members (invites, peer list) needs a ProgressPals account. Joiners do not need to sign up — they just need an invite token.

Operators

Sign in on the website to get your account credentials, then export them as environment variables before running the operator-side commands.

auth

$export PROGRESSPALS_SUPABASE_URL=https://your-project.example

$export PROGRESSPALS_SUPABASE_PUBLISHABLE_KEY=...

$export PROGRESSPALS_SUPABASE_ACCESS_TOKEN=...

$export PROGRESSPALS_SUPABASE_REFRESH_TOKEN=...

Keep these values secret. They authenticate the CLI as you to the ProgressPals backend. Anyone with your access token can mint invites and revoke peers on your swarms.

Joiners

You don’t need an account. The invite token your operator gives you is sufficient — pals login redeems it and stores a per-peer credential locally.

Upgrade

upgrade

$pip install --upgrade progresspals

Common install problems

`ERROR: No matching distribution found`

Your Python version is unsupported. Use Python 3.10 or 3.11. Check with python3 --version.

CUDA mismatch

If torch installs but reports no CUDA, your wheel and driver versions probably don’t match. Install the CUDA-matched torch wheel first, then pip install progresspals.

`bitsandbytes` fails on macOS

On Apple Silicon, bitsandbytes uses a CPU fallback. If install fails completely, you can disable its welcome message with export BITSANDBYTES_NOWELCOME=1; the package still imports.