Home / 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,httpxandjsonschema(plustomlion Python 3.10). Each release publishes aconstraints.txtwith 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. The installer needscurland eithersha256sumorshasum, and it refuses to run as root. - Check your machine:
sparetokens doctorreports 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~/.sshor~/.configexists to read), no network, its own process view, no capabilities, a clean environment and a seccomp filter. Install it withsudo apt install bubblewrap(ordnf,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.
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_KEYin your environment.openai-api,xai,openrouter: the matching key in your environment.local: a reachable OpenAI-compatible server. The default is Ollama athttp://127.0.0.1:11434/v1.none: no model, only the sandbox.
See 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.
Edit this page on GitHub: available when the repository opens.