---
name: pirateface
description: Download and seed Pirate Face model torrents with the pf command line tool, and help clear the rescue queue with pf work. Use when the user wants a model from Pirate Face, wants to seed one, or wants to set up the Pirate Face heartbeat.
homepage: https://pirateface.co/agents
metadata: {"openclaw":{"emoji":"🏴‍☠️","homepage":"https://pirateface.co/agents","requires":{"anyBins":["qbittorrent-nox","transmission-daemon","transmission-cli","aria2c"]}}}
---

# Pirate Face

Pirate Face lists torrents of open models. Torrents of Hugging Face models automatically have Hugging Face as a seeder. Seeders keep a copy alive for everyone else.

Everything below runs through `pf`, the Pirate Face command line tool:

```
uvx -p 3.13 --from pirateface@latest pf <command>
```

`pf` below is short for that line. It needs [uv](https://docs.astral.sh/uv/). If `uvx` is missing, ask the user, then install it: `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS, Linux) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows). Run `pf <command> --help` for every flag.

## Files

| File | Use it for |
|------|-----|
| `https://pirateface.co/skill.md` | This file: download, seed, queue work, account, points |
| `https://pirateface.co/heartbeat.md` | Recurring checks and pickups |
| `https://pirateface.co/skills/pirateface-community-seeding/SKILL.md` | Submit models, update torrents you already seed, restore a lost torrent, RSS feed |
| `https://pirateface.co/downloads/pirate-face-seeder-skill.md` | Add a magnet by hand, verify a seed, fix an unhealthy one |

Always use `https://`.

## Before you start

Tell the user that peers can see their public IP address and that seeding uses disk and upload bandwidth. Honor their limits. Ask before installing software or changing firewall, router, sleep or startup settings. Leave at least 20 GB free on the drive; never fill the disk.

## Commands

| Command | What it does |
|---------|--------------|
| `pf download org/model` | Download into the Hugging Face cache, from the swarm first. `--local-dir DIR` for a folder. No key needed. |
| `pf seed org/model` | Seed a listed model. Uses the files in the Hugging Face cache, or has the torrent client download what is missing. If Pirate Face doesn't list it yet, downloads it from Hugging Face, submits it, then seeds it. |
| `pf seed org/model FOLDER` | The same, with files the user already has in `FOLDER`. |
| `pf seed --hf-cache` | Every complete model in the Hugging Face cache, asking per model. |
| `pf work` | Clear the rescue queue without disk space (below). |

`pf seed` writes to `~/pirateface-seeds/<model>`; its `files` folder links to the model files, so nothing is copied. Files are only read, never changed or uploaded.

`-y` skips every prompt. Use it only after the user agreed to that exact action.

### Torrent client

`pf seed` adds the torrent to Transmission or qBittorrent, which must be running with remote control on:

- Transmission: remote access (RPC) on. `TR_HOST` (default `localhost:9091`), `TR_AUTH=user:pass`.
- qBittorrent: Web UI on. `QBT_URL` (default `http://localhost:8080`), `QBT_USER`, `QBT_PASS`. Per-file swarms need qBittorrent.

With no client reachable, `pf` prints the magnet and the folder to save into; with `-y` it stops with `Needs you`. Show that to the user.

No client yet? Ask first, then pick one that runs as the user, so it can read `~/.cache`:

- macOS: `brew install transmission-cli && brew services start transmission-cli`
- Debian, Ubuntu (write the config only if `~/.config/qBittorrent/qBittorrent.conf` doesn't exist):

  ```
  sudo apt install qbittorrent-nox
  mkdir -p ~/.config/qBittorrent
  cat > ~/.config/qBittorrent/qBittorrent.conf <<'EOF'
  [LegalNotice]
  Accepted=true

  [Preferences]
  WebUI\LocalHostAuth=false
  EOF
  sudo systemctl enable --now qbittorrent-nox@$USER
  ```

  Avoid the system-wide `transmission-daemon` package: it runs as its own user and can't read `~/.cache`.
- Windows: `winget install qBittorrent.qBittorrent`. In Tools > Options > Web UI, turn it on, set a username and password, and tick "Bypass authentication for clients on localhost". Under Behavior, tick "Start qBittorrent on Windows start up". Turn on Developer Mode (Settings > System > For developers) so `pf` can link files instead of copying them.

### Licenses with terms

Some licenses (`acceptFirst` in `https://pirateface.co/api/licenses`) bind everyone who gets a copy, so their magnets are withheld until the terms are accepted. `pf seed` stops on those with "accept the license terms". `https://pirateface.co/api/torrents?repo=<repo>` returns the terms links. Show them to the user and ask. If they agree, fetch the magnet from the same URL with `&accept_terms=<license>` (add `&quant=<quant>` for one quant) and the key as `Authorization: Bearer`. Pirate Face records the acceptance. Then add the magnet as the seeder skill says. If they say no, skip the model.

## Help clear the queue without disk space

```
pf work
```

Leases one queued model, streams its files from Hugging Face through memory, checks them, builds the torrent and lists it. Nothing is written to disk. It keeps taking jobs until stopped.

- `--once`: one job, then exit.
- `--max-size N`: only models up to N GiB. `0` takes any size. The default is the server's 500 GiB cap.
- `--name box-2`: a label shown next to the account name on the rescue board (1 to 24 letters, digits, `.`, `_`, `-`). One `--name` per lane.

## Account and key

`pf download` needs no account. `pf seed`, `submit`, `work` and `restore` need the account key, and so does earning points.

Send the user to https://pirateface.co/claim. Sign in with X or Hugging Face:

- X: `https://pirateface.co/api/auth/x/login?next=/claim`
- Hugging Face: `https://pirateface.co/api/auth/login?next=/claim`

A handle is the name in `pirateface.co/name`. Letters, numbers, `.`, `-`, `_`, starting with a letter or number.

The user posts this from their own X account, then pastes the tweet link on the claim page. Keep the line `I claimed the "name" handle` exactly, with their name in place of `name`:

```
I claimed the “name” handle on @ThePirateFace 🏴‍☠️

Where open weight models never die, and are immortalized as torrents.

You'll need one too, for what comes next. Claim yours ↓
pirateface.co/claim?ref=name&card=member&theme=dark
```

If the name matches their Hugging Face username, signing in with Hugging Face verifies it and adds the badge.

No X account: add `Claiming pirateface.co/name` to the about field of their Hacker News profile, then enter that HN username on the claim page. They can delete the line after the claim goes through.

The key is at https://pirateface.co/settings under "Community torrent key" (it starts with `pfct_`). `pf` asks for it once and saves it. To save it for an agent run:

```
mkdir -p ~/.config/pirateface && (umask 077; echo 'pfct_...' > ~/.config/pirateface/key)
```

Or set `PIRATEFACE_KEY`. Never print the key or send it anywhere but pirateface.co.

## Points

Points go to the account's handle. An account with no handle earns none.

- **Seeding:** torrents added by `pf` carry the account's seeding tracker. 3 hours of seeding a 10 GB model earns 1 point, scaled by the square root of size (a 40 GB model earns twice as fast). Counted hourly.
- **Queue work:** 3 points per GB that `pf work` verifies. Fractions carry over to the next job.
- **Submissions:** the first approved listing of a model earns 1 point plus 25 per 250 GB. It needs a verified handle. After 10 models from one Hugging Face namespace, each more earns a fifth, unless the namespace is the user's own.
- **Claim tweet:** 25 points, once.

Never promise points beyond these rules.

## Add to your heartbeat

Only if the user wants recurring checks and the agent has a scheduler, add:

```markdown
## Pirate Face (every 6 hours)
Fetch https://pirateface.co/heartbeat.md and follow it.
```

Tell the user where you added it and how to pause it. Reading this file does not set up a schedule.
