Guide

Operator: start a swarm from scratch.

You’re the person assembling the cluster. This walks through everything: installing the CLI, connecting your account, registering a swarm, inviting your pals, and running the first server.

Install the CLI

A virtual env is the cleanest way. Python 3.10 or 3.11 only.

install

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

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

$pip install progresspals

Connect your account

Operator-side commands authenticate against the ProgressPals backend. Export your access + refresh tokens from your account dashboard:

account

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

$export PROGRESSPALS_SUPABASE_PUBLISHABLE_KEY=...

$export PROGRESSPALS_SUPABASE_ACCESS_TOKEN=...

$export PROGRESSPALS_SUPABASE_REFRESH_TOKEN=...

Don’t commit these to git. They authenticate you to the backend.

Initialize the local config

init

$pals init

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

Register the swarm

One swarm per config directory. Pick a name that’ll help you tell them apart later.

swarm create

$pals swarm create --name "my-team"

✓ swarm registered · swarm_id stored in config

Mint invites for your pals

Single-use, short-lived. Mint one per teammate so they each get a fresh token.

invite create

$pals invite create --max-uses 1 --expires-hours 48 --note 'alice'

⟶ Invite token (save it now):

pp_inv_a8c4f2e9b1d6a7c3...

Send the token to alice over a secure channel — Signal, encrypted email, 1Password share. Don’t paste it into chat.

Start hosting layers

The first server in the swarm. Use --public if your pals are off-machine.

create

$pals create meta-llama/Llama-3.1-8B --public

✓ starting NEW swarm

multiaddr: /ip4/HOST/tcp/PORT/p2p/PEER_ID

Copy the multiaddr line — your pals need it (along with their invite token) to join.

Watch the swarm fill up

A read-only TUI that shows peers, invites, and status side-by-side.

dash

$pals dash

(Optional) expose an OpenAI endpoint

Once the swarm covers the full model, run an OpenAI-compatible server. Your team’s tools (Cursor, Aider, Continue) can point at it.

serve

$pals serve meta-llama/Llama-3.1-8B

✓ listening on http://127.0.0.1:8080/v1

To make it reachable from other machines on your LAN, see the Serve guide.

Ongoing operator chores

pals invite list — audit which tokens are outstanding.
pals invite revoke <prefix> — pull an invite that hasn’t been redeemed yet.
pals peers kick <peer_id> — remove someone who has joined.

Next steps

Guide

Serve OpenAI endpoint

Expose your swarm safely to your team's tools.

Concepts

Security & trust

Trust model + the safe-default rules.

CLI

pals invite

Full invite-lifecycle reference.

CLI

pals peers

Listing, kicking, revoking peers.