Source: https://sparetokens.ai/docs/requirements
Description: What you need to run the SpareTokens worker: Python, macOS or Linux with a sandbox, an AI account or local model, and the Lean tools for formalization tasks.

[Home](https://sparetokens.ai/) / [Docs](https://sparetokens.ai/docs) / System requirements

# System requirements

What the SpareTokens worker needs on macOS, Linux or Windows (WSL2): Python, an AI account or local model, and an OS sandbox for shell tasks.

What you need to run the worker. Everything runs on your machine under your own account.

## Platform
- **Python:** 3.10 or newer. The worker's runtime dependencies are `claude-agent-sdk`, `httpx` and `jsonschema` (plus `tomli` on Python 3.10). Each release publishes a `constraints.txt` with the exact versions it was tested with, and the installers use it.
- **Operating system:** macOS, Linux, or Windows through WSL2. Native Windows works for tasks that need no shell. See the table below.
- **Installers:** `pipx`, Homebrew or the one-line installer. [Available at launch] See the [install page](https://sparetokens.ai/install). The installer needs `curl` and either `sha256sum` or `shasum`, and it refuses to run as root.
- **Check your machine:** `sparetokens doctor` reports your OS, sandbox, providers found and config directory, and whether the coordinator answers.
- **License:** the worker is Apache-2.0.

## What works on each system
| Feature | macOS | Linux | Windows with WSL2 | Windows, native |
| Setup, status, history, rules, pausing | Yes | Yes | Yes (it is Linux) | Yes |
| Model-only tasks, such as literature checks | Yes | Yes | Yes | Yes, with a provider that has web search |
| Shell and solver tasks (`run_solver`, `re_verify`, compute, `code_fill`) | Yes, `sandbox-exec` | Yes, bubblewrap | Yes, bubblewrap | Refused, with a WSL2 hint |
| Lean formalization | Yes, if `lake` is installed | Yes, if `lake` is installed | Yes, if `lake` is installed | No |
| Background service | launchd | `systemd --user` | `systemd --user` (turn systemd on in WSL2) | Task Scheduler |
| Config folder | `~/.config/sparetokens` | `~/.config/sparetokens` (or `$XDG_CONFIG_HOME`) | same as Linux | `%APPDATA%\SpareTokens` |
| State folder | `~/.local/state/sparetokens` | `~/.local/state/sparetokens` (or `$XDG_STATE_HOME`) | same as Linux | `%LOCALAPPDATA%\SpareTokens` |

Run `sparetokens status` to see your platform and whether the sandbox works. Where something is refused, the message says why and how to fix it. Nothing ever falls back to running a shell without a sandbox.

## An OS sandbox, for shell and solver work

Anything that runs a shell or a solver goes through an OS sandbox.
- **macOS:** `sandbox-exec`, which is built in. Reads of credential folders are denied and writes are limited to the task folder.
- **Linux and WSL2:** bubblewrap (`bwrap`). The command gets a new, nearly empty filesystem: the system runtime read-only, the task folder as the only writable path, no home folder at all (so nothing in `~/.ssh` or `~/.config` exists to read), no network, its own process view, no capabilities, a clean environment and a seccomp filter. Install it with `sudo apt install bubblewrap` (or `dnf`, `pacman`, `zypper`, `apk`). The worker runs the real profile once to check that it works, because many containers and some hardened hosts forbid the user namespaces bubblewrap needs.
- **Native Windows:** no sandbox we trust. Use WSL2, described in [the quickstart](https://sparetokens.ai/docs/quickstart#windows).

With no working sandbox, no shell is offered, solver tasks are not advertised, and `--provider none` refuses to start. Literature tasks do not need a shell.

## A source to donate from
- **`anthropic-api`:** `ANTHROPIC_API_KEY` in your environment.
- **`openai-api`, `xai`, `openrouter`:** the matching key in your environment.
- **`local`:** a reachable OpenAI-compatible server. The default is Ollama at `http://127.0.0.1:11434/v1`.
- **`none`:** no model, only the sandbox.

See [providers](https://sparetokens.ai/docs/providers) for details.

## Lean, for formalization tasks

If `lake` or `lean` is on your PATH, shell use is allowed and the sandbox works, the worker advertises the `lean` capability. Lean tasks also need a tier 3 model. You can contribute without Lean: it is only needed for that one task type.

## Disk and files

On macOS and Linux, config lives in `~/.config/sparetokens`, state in `~/.local/state/sparetokens`, and task work directories under `~/.sparetokens/work`. On native Windows they are `%APPDATA%\SpareTokens`, `%LOCALAPPDATA%\SpareTokens` and a `work` folder inside the state folder. Override the first two anywhere with `SPARE_CONFIG_DIR` and `SPARE_STATE_DIR`.

## Network

The worker talks to your provider and to the coordinator. The coordinator URL is set with `--coordinator` or `SPARE_COORDINATOR`. [Planned] A public coordinator URL arrives with the beta.

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