SpareTokens

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, 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. 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

FeaturemacOSLinuxWindows with WSL2Windows, native
Setup, status, history, rules, pausingYesYesYes (it is Linux)Yes
Model-only tasks, such as literature checksYesYesYesYes, with a provider that has web search
Shell and solver tasks (run_solver, re_verify, compute, code_fill)Yes, sandbox-execYes, bubblewrapYes, bubblewrapRefused, with a WSL2 hint
Lean formalizationYes, if lake is installedYes, if lake is installedYes, if lake is installedNo
Background servicelaunchdsystemd --usersystemd --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.

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 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.