Source: https://sparetokens.ai/docs/quickstart
Description: Install the SpareTokens worker, run setup with a spend cap, and watch your first verified result. Beta steps, clearly labelled until the worker is public.

[Home](https://sparetokens.ai/) / [Docs](https://sparetokens.ai/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](https://sparetokens.ai/start) follow the same steps for your situation: [API credit](https://sparetokens.ai/start/api-credit), [a local model](https://sparetokens.ai/start/local-model), [your AI agent](https://sparetokens.ai/start/agent) or [a company or lab](https://sparetokens.ai/start/teams), 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](https://sparetokens.ai/join) 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](https://sparetokens.ai/install) 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](https://sparetokens.ai/docs/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](#macos), [Linux](#linux), [Windows](#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](https://sparetokens.ai/install) 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](https://sparetokens.ai/docs/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](https://sparetokens.ai/docs/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](https://sparetokens.ai/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](https://sparetokens.ai/docs/schedules-and-pausing).

## Where to next
- [Limits and protections](https://sparetokens.ai/docs/limits-and-protections): what keeps you in control.
- [CLI reference](https://sparetokens.ai/docs/cli): every command and flag.
- [Troubleshooting](https://sparetokens.ai/docs/troubleshooting): if something does not work.

---
Part of SpareTokens (https://sparetokens.ai/). Full site index for agents: https://sparetokens.ai/llms.txt
