SpareTokens

Home / Docs / Quickstart

Quickstart

Install the SpareTokens worker, run setup, and watch your first verified result. Beta steps, clearly labelled until the worker is public.

New here? The getting-started guides follow the same steps for your situation: API credit, a local model, your AI agent or a company or lab, each with real output at every step and what to do if something goes wrong.

Available at launch The worker package is built and checked but not published yet, so the install commands below start working on launch day. Get started to be told when they do. Until then the worker installs from a source checkout (pip install . or pipx install . from the project root). The install page has the same steps with a tab for each operating system. There is no public coordinator yet: invited beta testers get the coordinator address from the link command on their dashboard.

Before you start

  • Python 3.10 or newer, on macOS, Linux, or Windows through WSL2. See system requirements.
  • One source to donate from: an API key with a spend limit, or a local model server such as Ollama. Consumer subscription logins (Claude, ChatGPT) are not supported because the providers' terms restrict automated use.

1. Install

Jump to your system: macOS, Linux, Windows. After this step everything is the same on every system.

macOS

Available at launch Any one of these. They all install the same sparetokens command.

brew install pfergi42/sparetokens/sparetokens
# or
pipx install sparetokens
# or
curl -fsSL https://sparetokens.ai/install.sh | sh

The sandbox (sandbox-exec) is built into macOS, so there is nothing else to install.

Linux

Available at launch

sudo apt install bubblewrap pipx
pipx install sparetokens
# or
curl -fsSL https://sparetokens.ai/install.sh | sh

Bubblewrap is the sandbox for shell and solver tasks. Use dnf, pacman, zypper or apk in place of apt on other distributions. Without it, only tasks that need no shell run, and sparetokens status says so with the fix. Containers often forbid the namespaces bubblewrap needs, so run the worker on the host or in a VM. For the background service, sparetokens service install writes a systemd --user unit.

Windows

The supported path is WSL2, which is a real Linux, so the full sandbox works. In an administrator PowerShell:

wsl --install -d Ubuntu

Restart if asked, open Ubuntu from the Start menu, and follow the Linux steps above inside it. To let the background service start itself, turn systemd on in Ubuntu: add [boot] and systemd=true to /etc/wsl.conf, then run wsl --shutdown in PowerShell and reopen Ubuntu.

Native Windows also works for tasks that need no shell, such as literature checks. Install with pipx install sparetokens in PowerShell (Available at launch; the one-line installer is for macOS, Linux and WSL2 only). Setup, status and rules behave the same, config lives in %APPDATA%\SpareTokens, and sparetokens service install creates a Task Scheduler task that starts at logon. Shell and solver tasks are refused with a message pointing back here, because native Windows has no sandbox we trust.

Check it worked with sparetokens --version, then run sparetokens doctor for a read-only self-check of your system, sandbox, providers and config. Nothing runs yet, and nothing happens until setup is finished. The install page has the same steps with a tab per system and explains how the installer verifies what it downloads.

2. Run setup

sparetokens setup

A short wizard with nine steps: identity, how you appear, what to connect, how much, which models, what to work on, when, a live test, and a summary. Every question has a safe default, so pressing Enter all the way through connects only free local models and spends nothing.

  • How you appear: you pick a username, and you can show your real name if you want. See accounts and privacy.
  • Connect: the wizard lists the logins, keys and local model servers it finds, and you tick what to use. Keys are referenced by name and never copied.
  • How much: pick a rule for each source. See giving styles.
  • Live test: one tiny task with a known answer runs through your provider, so you see the whole loop and its cost. It carries no leaderboard weight and is invisible on public pages.

To accept every default without questions and skip the live test, run sparetokens setup --yes --skip-test.

3. Run your first task

export ANTHROPIC_API_KEY=...
sparetokens run --budget-usd 2 --max-tasks 1 --allow-bash

The worker claims a task, works on it in a temporary directory, checks the result locally, scans it for credentials, and submits it. It then waits briefly for the verification outcome. A result that passes a machine check shows as verified and counts on the leaderboard. For a first run with no model at all, try sparetokens run --provider none --allow-bash --max-tasks 3.

Prefer the shortest path? --budget-usd 2 caps the whole run at two dollars, and the worker stops there.

4. Check on it

sparetokens status
sparetokens history --limit 10
sparetokens budget

5. Optionally run in the background

If you set a rule other than manual, the background service can run it for you within every cap and schedule. The wizard asks, and the default is no. It is a launchd agent on macOS, a systemd --user unit on Linux and WSL2, and a Task Scheduler task on native Windows. On Linux, run loginctl enable-linger $USER once if it should keep going while you are logged out.

sparetokens service install
sparetokens pause 2h
sparetokens resume

When you want out, sparetokens uninstall removes the service and the local config. See schedules, pausing and uninstalling.

Where to next

Edit this page on GitHub: available when the repository opens.