← back to the site GitHub

Get started

Three ways to donate your idle AI compute — pick the one that fits. Every path needs a pairing code from the pool's web UI (Account → Generate pairing code), and your provider keys never leave your machine: only prompts and answers move.

💻 Your machinetwo commands, zero installs 🐳 Dockerset-and-forget on any box ⚙️ GitHub Actiondonate spare CI minutes

💻 Your own machine

You need: Python 3.11+ and at least one way to run models — an AI CLI (claude, codex, gemini, grok, cursor-agent), a metered API key, or Ollama / LM Studio running locally.

1

Pair once

Grab the connector from the repo, run it with your pairing code. It remembers the pairing in ~/.sparecycles/node.json.

git clone https://github.com/stevologic/spare-cycles.git
cd spare-cycles
python connector/node_connector.py --server https://your-pool.example.com --code AB12-CD34
2

Run it

That's the whole job. It auto-detects your CLIs, API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY) and local Ollama / LM Studio models, and serves only the projects you've chosen to support.

python connector/node_connector.py
3

Check on it

python connector/node_connector.py --status
#  node 'my-laptop' → account @you
#  pool sees: ONLINE · 41 job(s) completed

Want it always-on? nohup python connector/node_connector.py & or a systemd unit — see the deploy guide.

Try it without spending a token: add --runners echo — a built-in test runner that just echoes prompts back, so you can watch the full loop work.

🐳 Docker

You need: Docker. The image is ghcr.io/stevologic/spare-cycles (amd64 + arm64 — a Raspberry Pi counts).

1

Pair once

The node identity is saved into the sparecycles volume, so you only do this the first time.

docker run -it -v sparecycles:/data ghcr.io/stevologic/spare-cycles \
  --server https://your-pool.example.com --code AB12-CD34
2

Serve forever

Pass whichever provider keys you donate with — they stay inside the container on your machine.

docker run -d --name sparecycles-node --restart unless-stopped \
  -v sparecycles:/data \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  ghcr.io/stevologic/spare-cycles
3

Watch it work

docker logs -f sparecycles-node
docker run --rm -v sparecycles:/data ghcr.io/stevologic/spare-cycles --status
Donating a local Ollama? Let the container reach it on the host:
--add-host=host.docker.internal:host-gateway -e OLLAMA_HOST=http://host.docker.internal:11434

⚙️ GitHub Action — donate your CI minutes

You need: a GitHub repo. A scheduled workflow checks in, serves the queue for N minutes, and leaves — quitting early if there's no work.

1

Get a node token

Pair once on any machine (step 1 of either method above), then copy node_token (scn_…) out of ~/.sparecycles/node.json.

2

Add repo secrets

Repo → Settings → Secrets and variables → Actions: SPARECYCLES_NODE_TOKEN plus the provider keys you donate with (ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY — any subset).

3

Add the workflow

Save as .github/workflows/donate.yml (full example here):

name: SpareCycles donor check-in
on:
  schedule: [{ cron: "17 3 * * *" }]   # nightly
  workflow_dispatch: {}
jobs:
  donate:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: stevologic/spare-cycles@main
        with:
          server: https://your-pool.example.com
          node-token: ${{ secrets.SPARECYCLES_NODE_TOKEN }}
          models: "claude*,gpt*"
          minutes: 20
          idle-exit: 120
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
Note: CI runners have no AI CLIs installed, so Action donations flow through the direct API runners — metered keys, the ToS-clean way to give.

🏊 Run your own pool

The whole coordinator is one Python process + one SQLite file. It never runs inference, so a $6 VPS — or your desktop behind a tunnel — is plenty.

git clone https://github.com/stevologic/spare-cycles.git
cd spare-cycles
pip install -r server/requirements.txt
uvicorn server.main:app --port 8377

Open http://localhost:8377 — create an account, add your project, generate pairing codes. For HTTPS, systemd, backups and monitoring, follow the deploy guide.