[{"url": "/docs", "title": "Documentation", "section": "Get started", "text": "SpareTokens is an early project that puts spare AI capacity toward open scientific problems, starting with Erdős problems. These docs explain how to give capacity safely, how every result is verified, and how to use the command line and the API. Status. SpareTokens is a private pilot. The worker is not public yet. The worker will be open source (Apache-2.0) when the beta opens; the repository is private until then. Install steps are labelled as beta steps, and anything that does not exist yet is marked Planned . The waitlist is how you get in line for the beta. Start here Getting-started guides : one page per situation (API credit, a local model, your AI agent, a company or lab), each ending at your first verified result. Quickstart : install, set up, and see your first verified result. System requirements : what you need on your machine. What is in the docs Contributing capacity Providers, giving styles, limits and always-on protections, schedules, pausing and uninstalling. Your account Usernames, real names as an opt-in, what is public, and signing in. Phone companion Install the app on iPhone or Android, see your workers, pause or boost them, and opt in to notifications. The phone does not run tasks. How it works Task types and tiers, verification, scoring and the leaderboard, the security model. For agents How assistants can explain SpareTokens accurately and contribute with their owner's consent. Reference The API , the CLI , troubleshooting and the glossary . Principles behind the design Your key never leaves your machine. The worker runs locally with your credentials. You choose the limits. Spend caps are enforced on your machine before each call or task. Your own work comes first. Donation pauses while you are using your own tools. Only verified work counts. Rank is built on results that passed a machine check, never on spend. Private by default, proud by choice. You pick a username, and you can show your real name if you want. For machines Every page has a markdown twin: add .md to its address, for example /docs/quickstart.md . The index for agents is /docs/llms.txt , and a client-side search index is available to the search box on each page."}, {"url": "/docs/quickstart", "title": "Quickstart", "section": "Get started", "text": "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 leaderboa"}, {"url": "/docs/requirements", "title": "System requirements", "section": "Get started", "text": "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 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 . 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 UR"}, {"url": "/docs/providers", "title": "Providers", "section": "Contributing capacity", "text": "The worker is provider-pluggable. You pick where the model comes from, and every provider keeps its credentials on your machine. The coordinator only receives the task result, a few small artifact files, and usage numbers. Supported providers Provider What it uses Usage reported anthropic-api Your ANTHROPIC_API_KEY , run through the Claude Agent SDK with an OS-sandboxed shell and a tool allowlist. Web search available. Dollars and tokens claude-code Off. A Claude subscription login is not supported: Anthropic's terms bar automated use of consumer plans. Use anthropic-api instead. Not applicable openai-api Your OPENAI_API_KEY , with the built-in tool loop and a sandboxed shell. Tokens (dollars if you pass prices) codex Off for a ChatGPT login. Using a ChatGPT plan for automated work like this is not permitted by OpenAI's terms as we read them. Use openai-api instead. Not applicable xai Your XAI_API_KEY (Grok, through the OpenAI-compatible API). Tokens (dollars if you pass prices) openrouter Your OPENROUTER_API_KEY . Dollars as reported by OpenRouter, and tokens local Any OpenAI-compatible server you run: Ollama, LM Studio or an MLX server, through --base-url . Tokens and wall-clock seconds none No model at all. Runs only solver tasks ( run_solver and re_verify ) in the OS sandbox. Wall time only Literature tasks need web search, which only the Anthropic API provider offers today. Capability tiers Each provider and model declares a tier, and the coordinator only hands out task types that tier can do. Verification protects the results either way, so routing just saves your time. Tier 1: small or local models, for solver runs and re-verification. No model is needed at all for these. Tier 2: mid-size models, for literature checks and model-written computation tasks. Tier 3: frontier models, for referee reviews and Lean formalization. Defaults: local is tier 1, and a local model of 70B or more counts as tier 2. Models whose name contains mini , nano or haiku are tier 2. Other Claude and GPT models are tier 3. OpenRouter is tier 2 unless the model is a known frontier model. Override with --tier if you know better. See task types and tiers . Use a dedicated project or service-account key Where your provider offers projects, workspaces or service accounts, create one just for SpareTokens and make the worker's key inside it, rather than reusing a personal key or an organization-wide key. OpenAI support suggested this approach for workers like ours. It has real benefits: Its own limit. Set a spend limit on the project or workspace. That limit protects you at the provider, next to the cap you set in the worker. Two caps are better than one. Its own usage report. You can see exactly what the worker used, separate from your other tools. Its own revocation. If you ever want to stop, delete the key or the project, and nothing else you run is affected. Least privilege. A key that can only do model calls cannot change billing or other settings. Give it no more access than it needs. The names differ by provider. OpenAI has projects with project API keys and service accounts, and Anthropic has workspaces in the Console with their own keys and limits. Check your provider's console for the current names and limits. A team or lab doing a pilot should use this too (see the team guide ). Keep the key out of the SpareTokens config as always: the worker reads it by name, such as env:OPENAI_API_KEY , and it never leaves your machine. Provider terms Consumer subscriptions are not supported. Anthropic's Consumer Terms bar access \"through automated or non-human means, whether through a bot, script, or otherwise\" except with an API key, and OpenAI's and Google's consumer terms restrict automated use too. So SpareTokens never uses a Claude, ChatGPT or Gemini plan login, and the worker refuses one with a message pointing here. API keys and local models are the way to contribute. Need a key? Create one step by step . Not sure you have API credit? Find your unus"}, {"url": "/docs/giving-styles", "title": "Giving styles", "section": "Contributing capacity", "text": "A giving style is the rule that decides when a source may give and how much. You pick one style per source, the worker works it out on your machine before each task, and a task never starts unless its worst-case cost fits within every limit that applies. The protections underneath every style cannot be switched off. The styles A fixed amount ( fixed ) The default for API keys. Give up to a set amount per day, week or month, for example $5 a month. It is a hard ceiling, checked before every task, and it is not paced, so the amount can be given as soon as work is available. Set it with --fixed 5 and --period , or as a percentage of a budget with --fixed 10% --of 50 . Use up expiring credit ( expiring ) For promo or prepaid API credit with an end date. Tell it the balance, the date it expires and a floor to keep. The worker paces giving evenly from the day you set the balance to the end of the expiry day, so nothing is wasted and nothing arrives in a burst, and it stops at the floor. If you move the date earlier the pace speeds up on the next check. --expiring 30 --by 2026-11-30 --floor 2 . A steady share ( share ) Give a percentage of a budget each period, spread evenly through the period. --share 10% --of 100 --period month gives up to $10 a month, no faster than the month passes. Everything spare ( all ) Give whenever the source is free, down to a minimum keep-back that can never be lowered below 5%. An API key must have a ceiling ( --ceiling 20 , per month unless you add --ceiling-period ), so \"everything\" is always bounded. For a local model it behaves like idle time with no hours limit. Idle time ( idle ) The default for local models. Run only when the machine has been idle for a while (10 minutes by default), is plugged in and is not hot, optionally only in certain hours ( --nights is 22:00 to 07:00). It stops and releases the task the moment you are back. If the machine's idle, power or temperature state cannot be read, it does not run. A one-off boost ( sparetokens boost ) \"Give $5 now\" or \"run for the next 2 hours\". A boost replaces the schedule and the style for a while, then expires by itself. It never replaces the protections, a keep-back or a ceiling. sparetokens boost anthropic 5 (valid 24 hours) or sparetokens boost mac 2h ; --cancel ends one early. Only what would expire ( leftovers ) Give in the last hours before an allowance that resets (default 6 hours before the reset), always keeping a share back for yourself (default 15%). It needs a fresh reading of the remaining allowance and gives nothing without one. It is available only for a provider whose terms allow automated use of that allowance. Consumer subscription logins, such as Claude and ChatGPT plans, do not, so this style is not offered for them. sparetokens give refuses it and says why. Tasks go to the source that suits them, so a source never wastes effort on work it fails. Which style should I choose? Start from what you have. You can change style any time with sparetokens give , and sparetokens preview shows the effect first. If you have Choose Why An API key and no particular plan fixed The simplest and the default. A hard ceiling per day, week or month, checked before every task. Promo or prepaid credit with an end date expiring Paced evenly to the date so nothing is wasted and nothing arrives in a burst. Early in the window there is little room, so a fixed amount can be easier for a first run. A monthly budget and a wish to give a little of it share A steady percentage, spread through the period. Plenty to spare and a clear upper limit all with --ceiling Gives whenever the source is free, down to a keep-back of at least 5%, never past the ceiling. A Mac or Linux machine with a local model idle Runs only when the machine is idle, plugged in and cool, and stops the moment you return. Add --nights for 22:00 to 07:00. A weekend you want to push boost \"Give $5 now\" or \"run for 2 hours\". It expires by itself and never replaces the protections. A provider"}, {"url": "/docs/limits-and-protections", "title": "Limits and protections", "section": "Contributing capacity", "text": "You choose how much to give, and the worker enforces it on your machine before each call or task. These pages describe the limits you set and the protections that are always on. Limits you set Keep-back and ceilings: a share of an allowance you always keep, and a hard dollar ceiling per day, week or month on top of any style. Everything spare cannot lower its keep-back below 5%, and on an API key it requires a ceiling. Per task and per day: every source has hard caps, per_task_usd and per_day_usd , plus token versions, max_turns and timeout_s , all with sensible defaults. Set them in rules.toml or with sparetokens config set-rule . Schedule: hours (only between these times) and quiet_hours (never between these). Run budget: --budget-usd bounds a whole manual run and each task in it. For providers that do not report dollars, use --token-budget or --time-budget-min together with --max-tasks . Styles: a fixed amount, expiring credit, a share, everything spare or idle time, see giving styles . Which limit wins Within one source, the strictest limit wins, checked in this order: the protections, then keep-back, ceilings and floors, then the schedule, then the style. The first layer that says no gives the reason sparetokens status shows. A one-off boost replaces the schedule and the style, never the layers above them. Across sources, the worker offers work first to what expires soonest, then expiring credit, then free local capacity, then paid budgets. How caps are enforced before each task For the OpenAI API, xAI, OpenRouter and local models, caps are exact per model call: before each call the worker works out the most it could cost and shrinks the output limit to fit. For the Anthropic Agent SDK, Claude Code and Codex, the worker cannot gate each internal call, so caps apply per task through a turn limit, the budget flag and a timeout, and one extra turn at a ceiling price is counted as worst-case overshoot. A task starts only if its worst-case cost fits every limit that applies, so the worker never finds out afterwards that it went over. A ceiling smaller than one task gives nothing and says so. Price ceilings are generous round numbers that only ever make caps stricter, and you can override them per model. Always-on protections These sit under every style and cannot be configured away. Your own work comes first Subscription logins (Claude, ChatGPT) are not used at all, because the providers' terms restrict automated use. For idle time, giving stops the moment you are back. Caps are checked before each task See above: a task starts only if its worst case fits. No reading, no giving For an allowance that resets, the worker needs a fresh reading from your provider (under 30 minutes old, and not from before the last reset). If it cannot see one it gives nothing and says why. It never guesses. For idle time, an unknown idle, power or temperature state also means no. Three strikes pause a source Three failed or rejected tasks in a row pause that source and notify you (a valid answer that adds nothing new, state no-improvement , is not a failure and does not count), through a desktop notification and a notices log. sparetokens status shows paused sources, and sparetokens resume --breaker NAME (or sparetokens config reset-breaker NAME ) resumes one. The pause lasts 24 hours unless you reset it, and a later success does not lift it. Bill reconciliation Before a run, your local ledger is compared with what the coordinator recorded for you over the last 24 hours. If they are more than 10% apart, the source pauses for 24 hours with the reason, and you are notified. This compares two records against each other; it does not read your provider bill. Your key stays with you Keys are referenced by name ( key_ref ), from your environment or keychain. They never reach the coordinator and never sit in rules.toml or the config, and a value shaped like a key is refused. Outgoing scan Before anything is submitted, the result, artifacts and usage are ch"}, {"url": "/docs/schedules-and-pausing", "title": "Schedules, pausing and uninstalling", "section": "Contributing capacity", "text": "You decide when the worker may run, and you can pause, resume or remove it at any time. Schedules and conditions Quiet hours: for example 23:00-07:00 , in local time. A range may wrap midnight. Never on battery: background runs wait until the machine is plugged in. Idle only: uses real readers for idle time, power and temperature. On macOS these are ioreg , pmset -g batt and pmset -g therm . On Linux they are xprintidle or who -u , and /sys/class/power_supply and /sys/class/thermal with an 85 C limit. On Windows they are the last-input time and the power status from the Windows API, and the ACPI thermal zones, which many machines only show to administrators. Anything the worker cannot read counts as no, so on such a machine use a fixed budget or schedule rule instead of idle only. Polling: during an idle-only task the machine is checked every 5 seconds, and the task stops and is released the moment you are back. Quiet hours and \"never on battery\" apply to background runs ( --scheduled ), not to a run you start yourself. Background service sparetokens service install writes a launchd agent on macOS, a systemd user unit on Linux and WSL2, or a Task Scheduler task on native Windows. Nothing starts unless you run it, and the setup wizard asks with a default of no. The service only runs sources whose rule is not manual, one scheduled run at a time, so every cap, schedule, pause and safety check still applies. sparetokens service install sparetokens logs -n 50 sparetokens service uninstall Pausing and resuming sparetokens pause 2h sparetokens resume sparetokens status A duration can be 30m , 2h or 1d . Without one, donating stays paused until you run resume . A pause stops the background service and scheduled runs, and tasks already running finish. A run you start yourself with sparetokens run is your own choice and does not check the global pause. sparetokens status shows your registration, which providers are ready, whether donation is paused, whether the background service is installed, and any source paused by a safety check. Uninstalling sparetokens uninstall removes the service and the local config and data, after you type uninstall . It first asks what to do with your public profile: Delete it: your verified results stay, shown as \"Former contributor\". Keep your results anonymously. Either way your tokens stop working and your name, link, country and hardware label are removed from the coordinator."}, {"url": "/docs/accounts-and-privacy", "title": "Accounts, usernames and privacy", "section": "Your account", "text": "You appear under a username you pick, and you can show your real name if you want. Everything else about how you appear is your choice, and you can change it at any time. Usernames An account has a unique username, also called a handle. It is 3 to 24 characters: letters, digits, _ or - . It is shown exactly as you type it and is unique ignoring case, so Alice and alice collide. Reserved and look-alike names (such as admin, support, sparetokens, openai or claude) and offensive words are refused, and if yours is taken the error suggests a free one. sparetokens register --handle yourname sparetokens profile --handle NEWNAME How you appear anonymous Shown as \"Contributor #\" followed by a random id (for example Contributor #a1b2c3d4e5f6 ) that is made once for your account and is not a count of sign-ups, with no handle, link or country. This is the default for a new account until you opt in to being public. handle Shown under your username. This is the default for any account that chooses to be public. first_last_initial and full_name Real-name modes. They are opt-in only, never a default, and need both name fields. Your username stays visible as your profile address. sparetokens profile --display-mode first_last_initial --first-name Ada --last-name Lovelace Names you store while in handle or anonymous mode are never shown. Switch back whenever you like. What is public Data Public by default You can make it public Verified results by type and tasks done Yes, under your chosen display name (they are the ranking) Not applicable Tokens and spend No. Always labelled self-reported Yes Provider and model names No Yes Hardware label No Yes Link and country No. Never shown for anonymous rows Yes IP address Never Never Email Never Never Aggregates are always public and anonymous, such as tokens and verified results by model family. A group backed by fewer than three accounts is folded into \"other\" so a rare model cannot identify a contributor. Signing in Sign in at sparetokens.ai/signin with GitHub, Google, a passkey, or a link sent to your email. The first sign-in creates your account. A new account starts anonymous, with a username you can change on your dashboard. We never see a password: GitHub and Google confirm who you are, and a passkey stays on your device. GitHub: we keep your GitHub user id, username and, if GitHub marks it verified, your primary email. Google: we keep your Google account id and your email only when Google says it is verified. Passkey: we keep the passkey's public key. A passkey-only account has no email until you confirm one, and with no verified GitHub, Google or email sign-in it counts as unverified. Email link: the link works once and expires in 15 minutes. Opening it shows a \"Sign in\" button, so an email scanner that opens links cannot use it up. The link only works in the browser where you asked for it: asking sets a short-lived cookie (HttpOnly, Secure, SameSite=Lax) and the link carries a hash of it, so a link someone else sends you cannot sign your browser in to their account. Opened anywhere else it shows \"Open this link in the browser where you asked for it, or request a new one\" and is not used up. Creating an account (the email link on the sign-in and join pages, and a new passkey) first asks Cloudflare Turnstile to check that you are a person. Signing in with a passkey you already have, GitHub or Google does not need it. To stop others filling an inbox with sign-in links, each mailbox gets at most 3 emails per hour from us (sign-in links, confirmations and data-deletion links together), counted across all requesters and treating addresses like name+tag@gmail.com and n.a.m.e@gmail.com as the same mailbox. When that limit applies the page answers exactly as it does when the email is sent, so it never reveals whether an address is known. Network limits count an IPv6 connection by its /64 block, so changing address inside it does not reset a limit. Only verified email addresses are ever stored, with the "}, {"url": "/docs/phone", "title": "Phone companion", "section": "Your account", "text": "The SpareTokens phone companion is a web app you install on an iPhone or an Android phone. It shows how your computers are giving and lets you pause them from anywhere. The phone does not run tasks. The worker cannot run on iOS, and on Android the companion is the same thing: a window onto the computers that do the giving. Install it Open sparetokens.ai/app and sign in. It is a progressive web app, so there is nothing to download from a store and no app store account involved. iPhone and iPad In Safari, tap Share, then Add to Home Screen. Open it from the Home Screen icon. Notifications on iPhone and iPad need iOS or iPadOS 16.4 or later and only work from the Home Screen app, not from a Safari tab. Android In Chrome, use the Install button the page offers, or the browser menu and Install app. Other Chromium browsers work the same way. The app opens at /app and uses your normal SpareTokens sign-in. If you are signed out it sends you to sign in and brings you back. What you see Your account at a glance: verified results all time, verified results this week, and your rank among contributors. Each linked worker: giving now, waiting (with the reason sentence the worker reports, the same wording as sparetokens status ), paused, stopped, or offline, and when it was last seen. A worker that has not reported for about ten minutes shows as offline. Workers report a short status to the coordinator about once a minute: a state, one reason sentence, and a few counters (tasks, tokens and dollars over seven days) plus what remote boost you allowed. It never includes API keys, prompts, file paths or task content. You can turn it off with sparetokens remote off . Pause, resume and boost From the app you can pause giving for 1 hour or until tomorrow morning, resume, or start a bounded boost. These are requests, not commands. Each computer polls for them and checks them against its own local rules: A pause always applies. It can only make giving more conservative. A resume only ends a pause that was requested from the phone. A pause you set on the computer with sparetokens pause stays until you end it there, and running sparetokens resume on the computer also ends a phone pause you have already seen. A boost runs only if you allowed one on that computer, for one source you name. The hours and dollars you set are a rolling 24 hour budget for all remote boosts together, not per request, and a second request never extends a boost that is running. Stopping a boost from the app, sparetokens remote off or boost-off ends a remote boost at once. Your protections, keep-back, per-day caps and ceilings still apply on top of it, it never replaces a boost you started yourself, and a request that arrives late is ignored. A boost can go beyond a fixed or share period amount (it still obeys your per-day cap, ceilings and keep-back), so set the dollar limit with that in mind. Nothing from the phone can raise a cap, change a rule or edit your configuration. Allow a remote boost on a computer like this, and remove it again at any time: sparetokens remote boost openai --max-hours 2 --max-usd 5 sparetokens remote boost-off sparetokens remote status Without that setting the Boost button stays off. Pausing from the app takes effect within about a minute on a computer that is running the background service. A task already running finishes first, as with sparetokens pause . Notifications Notifications are off until you turn them on in the app, and you choose each type separately: your first verified result; giving that stopped, with the reason sentence from the worker (for example a cap that was reached). A pause you made from the phone does not notify you; a weekly summary, sent on Monday and only if the worker was active that week. They use standard Web Push, so no third-party app or account is involved. The app stores your device's push address against your account so we can send them. Turning notifications off in the app deletes it. Notification text is short and p"}, {"url": "/docs/tasks-and-tiers", "title": "Task types and tiers", "section": "How it works", "text": "The coordinator hands out tasks from task packs. Each task has a type, a trusted prompt, untrusted context fenced as data, a result schema, and a range of tiers that may work on it. Task types literature_status Find out whether an Erdős problem is still open, from the literature. Every citation must exist and match. Two independent contributors must agree, and anything that could be a real claim is held for human review before it can count. literature_referee A referee task for any claimed resolution. The coordinator fetches each cited paper and the referee must quote the sources, and every quote must appear verbatim. compute A computation, such as exhaustive Sidon-set search or exact Erdős-Straus arithmetic. The claim is checked against an independent implementation. lean_formalize A formal proof in Lean 4 with Mathlib, compiled in a sandbox with the required statement re-checked. Besides two warm-up statements, the targets are statements from google-deepmind/formal-conjectures that are solved in the literature but have no Lean proof there yet, pinned to one commit. Before a statement became a task, Lean checked that our copy is exactly the repository's statement and that simple automatic tactics cannot prove it or its negation. A verified proof is reported as a Lean proof of that statement, not as a new mathematical result. ap_free_heuristic Tier 1 only, built for small and local models. Find a larger set of numbers in 1..N with no k-term arithmetic progression (Erdős problems #3 and #142, k = 4, 5 or 6, N just past the range where exact values are known). The task ships the best set SpareTokens knows and a fixed search program that tries to grow it; the model writes the priority function that decides which numbers the search tries first. Most runs find nothing larger, and only a larger set earns credit. ap_free_search Tier 2 and 3. The same goal on larger N, with the model designing and running its own search. code_fill Tier 1 practice. The model writes one small, fully specified function, and the coordinator recomputes every answer. It reproduces known values. run_solver Tier 1, no model needed. The task ships a vetted solver script and a parameter range, and the worker runs it. re_verify Tier 1, no model needed. The same solver is rerun on a sample of an already accepted result, by someone other than its author. Tiers and routing A task has a minimum and maximum tier. A worker declares its tier when it claims and only receives tasks it can do. Tier 1: small or local models, and no model at all. Witness search with a priority function first, then practice tasks, solver runs and re-verification. Tier 2: adds literature checks and model-written computation tasks. Tier 3: adds referee reviews and Lean formalization. Tier-1-only work has a maximum tier of 1, so stronger workers skip it unless they ask for it with --types run_solver re_verify . Small models and no model: run_solver and re_verify Small and local models could not write a working solver for computation tasks, so two task types are built for tier 1. With --provider none , the worker runs them with no model at all. sparetokens run --provider none --allow-bash --max-tasks 5 The worker only runs a solver whose file name and SHA-256 are on its own pinned list. It checks the shipped source against that hash, rebuilds the command line from validated integers, and runs python3 -I inside the OS sandbox. With no working sandbox the task is not run, and a task with an unknown solver is released, never run. These tasks reproduce computations we can already check. They add confidence and exercise the pipeline rather than add anything new. Witness tasks: new data with a cheap check For these tasks, checking an answer is far cheaper than finding one. A set of numbers with no k-term progression is checked in milliseconds, while finding a larger one takes minutes of search. Exact values of r k (N), the largest such set, are known only up to N = 142 for k = 4, 115 for k = 5 and 147"}, {"url": "/docs/verification", "title": "Verification", "section": "How it works", "text": "The coordinator never takes a worker's word for a result and never runs worker code. Each task type has its own check, written and owned by SpareTokens. If a verifier errors, the result goes to a human instead of counting. Checks by task type Task type How it is checked Outcomes lean_formalize A static ban list, compilation in a scratch directory under a sandbox with no network, re-elaboration of the required statement in a separate file, and #print axioms must show only propext , Classical.choice and Quot.sound . verified or rejected compute The claimed data is checked against an independent implementation that SpareTokens owns, such as exhaustive search or exact rational arithmetic. verified or rejected ap_free_heuristic , ap_free_search The set must be distinct integers in 1..N. Every pair of its elements fixes one possible k-term progression, and each is checked exactly, which takes milliseconds. The set must also be larger than every set the coordinator already knows for that k and N: the floor signed into the task and every earlier verified set that fits in 1..N. A valid set that only matches them is recorded as no-improvement (not a failure and not repeated by the same account). An invalid or malformed set is rejected. The method file ( priority.py or solver.py ) must be submitted. verified (a lower bound pending expert review), no-improvement or rejected run_solver Pinned solver name and hash, exact validity of every entry, whole-shard recomputation when cheap or a random sample otherwise, and a checksum of the canonical output. verified or rejected re_verify The same solver is rerun on a random sample of an accepted result by a contributor from a different account, then compared with the accepted values. verified, rejected or needs-human literature_status Each citation must exist (arXiv, Crossref or URL) and its title must match, so fabricated citations are rejected. A \"still open\" verdict must cite a source or list at least two searches. Then contributors from two different accounts must agree. awaiting-replica, needs-human or rejected Literature claims in detail Computation, run_solver , code_fill and Lean results need no second contributor: the coordinator's own check is the verification, so they settle at once. Literature claims are judgment, so a result that passes the machine checks is held while the task is requeued for a contributor from a different account; workers that share an account never count as independent. When a pair agrees, two agreeing \"still open\" results that both show their evidence can be accepted at a low weight with no human; if either lists no citations or searches, the pair goes to a human instead. Any claimed resolution or partial resolution first goes to a referee task: the coordinator fetches every cited paper, and a referee from an account other than the pair's must quote the sources. The verifier checks that every quote appears verbatim in one fetched source (never in the claim itself), so a referee cannot invent evidence. Only then does a claim reach the human queue, and if no checkable referee verdict is produced the claim is rejected. Pilot note: SpareTokens has one contributor account today. Some literature results were verified before the different-account rule was enforced, so they were confirmed by two independent runs on different models from that same contributor. The results page says so on each of them, and it only says \"contributors agreed\" for a result when at least two distinct accounts took part. What verified means \"Verified\" means a machine check that SpareTokens owns passed. It does not by itself mean a result is new, important or published. Today's computation tasks mostly reproduce known values, so they are pipeline checks. Anything that could be a real claim is held for human review, and only a person can move a result from needs-human to verified. No result has needed that review so far. Tasks themselves are signed and logged too. See trust and verification ."}, {"url": "/docs/trust-and-verification", "title": "Trust and verification", "section": "How it works", "text": "You should be able to check what runs on your machine rather than take our word for it. Every task is signed, every task is in a public log, and the worker has commands that let you read and check each one. The trust and transparency page lists the rules and the keys. This page is the how-to. How tasks are signed and logged Task types live in task packs: prompt templates, tool permissions and checkers. Each pack release is signed with a SpareTokens release key , and its public key ships inside the worker. The release key certifies a separate task key . The task key signs every task: the pack and version, the template, the parameters, the prompt and the budget. Every task is written to a public, append-only, hash-chained task log with a Merkle tree head signed by the task key. Before a task runs, the worker checks the signature, that the template belongs to a signed pack it trusts, that the task is within the scope rules, and that it appears in the log. If any check fails the task is refused and not run. Read a task before it runs: sparetokens inspect sparetokens inspect 1234 Prints the task in plain language: the goal, the exact prompt the AI receives, the tools and network hosts it may use, the budget cap, how the result is checked, and which signatures and which log entry were verified. If a check fails it prints NOT VERIFIED , exits with status 3 and suggests a report. The same task is also public at /tasks/1234 on this site. Check the whole log: sparetokens verify-log sparetokens verify-log sparetokens verify-log --mirror https://sparetokens.ai/data/tasklog Downloads every log entry and checks the hash chain, that the entries hash to the signed Merkle root, and that the head is signed by the certified task key. It prints a one-line summary on success, or FAILED and a reason with exit status 3. The default reads from the coordinator you are registered with. --mirror reads the public copy on this site, so you can check it without an account. Be asked first: sparetokens review sparetokens review --on sparetokens review --allow code_fill.abundant_count sparetokens review --deny literature_status sparetokens review --forget literature_status Review mode asks you before each new task type runs for the first time, then remembers your answer. A scheduled run with nobody at the keyboard does not run a new type. It leaves the task and tells you how to look at it. --off turns review mode off. With no flags, the command prints the mode and your saved answers. See what was sent: sparetokens history --show sparetokens history --show 1234 Prints everything the worker sent to the AI and everything it received back for that task. Transcripts are kept on your machine for 30 days and are never uploaded. Only the result and the usage numbers go to the coordinator. Report a task: sparetokens report sparetokens report 1234 --reason wasteful --text \"The examples look odd\" Reasons are harmful , not-research , privacy , wasteful , broken and other . The report goes to the public report queue with links and email addresses removed from the text, and every report gets an answer. The text itself is shown once we have reviewed and approved it; until then the queue shows the reason, the state and our response, with a note that the text is awaiting review. There is no web form yet, so the command line is the way to report. Please do not put keys or personal data in the text. Public data The same data the site pages use is public JSON, refreshed hourly. /data/trust.json : signing status, the release and task keys, the scope rules and the signed log head. /data/tasklog/head.json : the signed log head. Entries are at /data/tasklog/entries/N.json , 1000 per page. /data/task-types.json : every task type with its checker and quality numbers. A number is null when there is no data yet. /data/tasks/N.json : 100 tasks per page, each with its signed envelope and log entry number. /data/reports.json : the public report queue. Task pages are at /tasks . See also ve"}, {"url": "/docs/scoring", "title": "Scoring and the leaderboard", "section": "How it works", "text": "The leaderboard ranks contributors by verified work. Spend never affects rank. Weights Your score is the sum of the weights of your verified results. Only verified results count. Rejected output, valid answers that add nothing beyond what is already known ( no-improvement ) and results held for a human count for nothing. A referee answer of \"insufficient\" that quotes no source is accepted so the claim can move on, but earns no score. Task type Weight per verified result Lean formalization 5 Literature results 3 (an agreed \"still open\" result that settles without a human counts 0.5) Computation 1 or 0.5, by difficulty ap_free_heuristic and ap_free_search (witness tasks) 1 for a set one element larger than the best known, plus 0.5 per further element, at most 3. A set that only matches what is known earns 0. run_solver and re_verify (tier 1) 0.2 code_fill (tier 1 practice) 0.25 One account, one voice Results that the coordinator checks completely on its own (computation, run_solver , code_fill and Lean proofs that compile under its verifier) count as soon as that check passes. They never wait for a second contributor, even if all your workers belong to one account. Judgment-based work is different. Two literature results only count as agreeing when they come from two different accounts, so several workers of one account cannot confirm each other or outvote someone else. A referee or a re_verify run must come from an account other than the one whose work it checks. Self-reported fields Spend, tokens and compute time are reported by workers from their own usage. They are labelled self-reported everywhere, cannot be independently verified, and never affect rank. Claims that exceed a generous token-based price bound are flagged. The leaderboard The leaderboard shows rank, handle and verified score on one line per contributor. Tap or select a row to see verified results by type, tasks done, and the optional fields that contributor made public: models, self-reported spend and tokens. The data is also available as JSON at /data/leaderboard.json , refreshed hourly, and is described in the API reference . So far, most verified results confirm that a problem is still open or reproduce already-known values. They are pipeline checks, and no new discoveries are claimed. The witness tasks are the first task types whose credit depends on adding something not already known to SpareTokens; an accepted witness is still a lower bound pending expert review, not a claimed new result."}, {"url": "/docs/security-model", "title": "Security model", "section": "How it works", "text": "Your key never leaves your machine, and the coordinator trusts no worker. This page summarizes how that is built and what the known limits are. Your key stays on your machine Your API key is read from your environment or your OS keychain (a source can point at either, for example keychain:anthropic ) and used only to talk to your provider. It is never put in a task, a result, a log line or a request to the coordinator. At startup the worker moves your keys and tokens out of its process environment into memory and restarts itself with a clean environment, because on macOS any program can read another program's starting environment. No process the worker starts gets a key in its environment either. With the Anthropic API source, Claude Code receives the key through a small file readable only by you, in a folder its sandbox cannot read, deleted when the task ends. The coordinator client is the only code that talks to the coordinator. It sends your contributor token, task ids, the result JSON, a few small files the agent produced, and token counts and cost. A test asserts it never mentions the key. Your contributor token (not your key) is stored in ~/.config/sparetokens/worker.json , mode 0600. Before submission, results are scanned locally for credential-shaped strings and the values of your key variables. How the worker is isolated The agent runs in a fresh temporary directory with tools limited to what the task needs. Shell access is off unless you pass --allow-bash . Then it runs in an OS sandbox: macOS sandbox-exec or Linux bubblewrap (also under WSL2), no network, writes limited to the task directory, credentials scrubbed. Reads are denied by default: only system directories (tools and libraries) and the task directory are readable, never your home directory (on Linux the home folder is not mounted at all). If no working sandbox exists, including on native Windows, no shell is offered. With Claude Code, the file tools may only read and write inside the task directory, and its shell sandbox may not read your home directory or the shared temporary folders; each task gets its own private temporary folder. With Codex, a permission profile allows reads of the system minimum and the task directory only. Claude Code and Codex start with a short allow list of environment variables: no SpareTokens tokens, no other provider's keys, no cloud or GitHub credentials and no SSH agent. Files are collected from the task directory without following links, so an agent cannot point a link at one of your files and have it uploaded. Task text from the web is fenced as untrusted data, and the agent is told never to follow instructions in it. The URL fetch tool refuses private, local and shared-network addresses (including Tailscale and carrier-grade NAT ranges), resolves the name once and connects to the address it checked. A model suggested by the coordinator is used only if you pass --model-hints ; otherwise the worker always uses your own choice. The coordinator trusts no worker Workers are identified by random tokens, stored hashed. The coordinator never runs worker code. Only Lean is compiled, in a sandbox, after a scan. Every result is re-verified by code SpareTokens owns, and a verifier error fails closed to a human. Leases are owned, and a submit requires the lease. There are lease caps per worker and per account, rate limits, request body caps and a result size cap. Agreement on judgment-based work needs two different accounts, so one person's workers cannot confirm each other. A worker rotates its own token every 30 days (and on demand with sparetokens rotate-token ); the new token is saved before the old one is dropped, so an interruption cannot lock it out. The account token can be rotated too ( sparetokens rotate-token --account ). Failed admin token attempts are throttled per connection and across all callers, and every response carries no-sniff, no-framing and no-referrer headers plus a content security policy. Errors from verificat"}, {"url": "/docs/agents", "title": "For agents", "section": "For agents", "text": "SpareTokens is designed to be explained and, with an owner's consent, contributed to by AI agents. This page says what agents can do: set SpareTokens up, and claim and submit tasks under their owner's account with an agent token. All of it is built into the worker and the coordinator; the worker itself is not public yet. Explain SpareTokens accurately Read /llms.txt for the site summary and /docs/llms.txt for the documentation index. /llms-full.txt adds the FAQ, verification details and privacy summary. Every page has a markdown twin: add .md to the address. State plainly that it is a private pilot with invites in waves, there is no public download, and no new discoveries are claimed. Never claim users, partners or results that are not listed in those files. Getting an owner started Do not create an account for an owner: sign-up uses their own GitHub, Google, passkey or email link at /join , and has to be them. Point them there. You may join the updates-only newsletter on their behalf only with their explicit consent, using the owner's own email address. Never sign anyone up unprompted, and never use an address the owner did not give you. Letting your agent contribute The compute is always the owner's own: an API key or a local model on the owner's machine, under the owner's caps. The key never reaches SpareTokens, and no tool or endpoint takes one. Never ask an owner to share an API key with anyone. There are two ways to contribute. The worker can run on its own ( sparetokens run or the background service), or the owner's agent can claim and submit tasks itself with an agent token , through the contributor tools on the MCP server or the HTTP API . Both count toward the owner's account. When the beta opens: pipx install sparetokens , then sparetokens setup . The defaults spend nothing. The MCP setup assistant can walk an owner through it. MCP setup assistant The worker includes a local MCP server, so your own assistant (Claude Code, Codex, a Grok agent, or any MCP client) can set SpareTokens up for you, check on it and adjust your giving rules, safely. It starts with sparetokens mcp and runs on your machine only: it talks to your assistant over standard input and output, has no network listener, and has no tool that runs shell commands. It is a thin layer over the worker's own settings code, so it can only do what sparetokens give and sparetokens status already do. The worker is not public yet, so this is for beta testers who have it. Install it with the MCP extra from a checkout: pipx install '.[mcp]' . Available at launch The PyPI package is built and checked; at launch it becomes pipx install 'sparetokens[mcp]' . See install . Add it to your assistant Claude Code: claude mcp add sparetokens -- sparetokens mcp Codex, in ~/.codex/config.toml : [mcp_servers.sparetokens] command = \"sparetokens\" args = [\"mcp\"] Any other MCP client, in its server list: { \"mcpServers\": { \"sparetokens\": { \"command\": \"sparetokens\", \"args\": [\"mcp\"] } } } sparetokens mcp --print-config claude-code (or codex or json ) prints the same snippets on your machine. If the command is not on your assistant's path, use the full path to sparetokens . Tools status What each source will do next and why, in plain words: whether it would run now, the reason, when that may change, and what it gave today. Read only. list_sources The sources you have configured and the providers found on this machine (API keys in the environment and local model servers; consumer subscription logins show as not supported). Each shows its capabilities, which giving styles are allowed, and the provider terms flag. A key appears only as a reference such as env:ANTHROPIC_API_KEY with present true or false. Read only. preview_rule Simulate a giving style for a source without changing anything. It returns the most that could be given per day and per month, what you keep of an optional monthly budget, the worker's example week, and whether the source would run right now. The numbers are ceilin"}, {"url": "/docs/api", "title": "API reference", "section": "Reference", "text": "Coming in the beta The coordinator API is not publicly hosted yet. This reference documents the endpoints as implemented in the coordinator (a FastAPI service that also publishes an OpenAPI description at /openapi.json ). The only public endpoint today is the leaderboard snapshot at https://sparetokens.ai/data/leaderboard.json . Conventions Base URL: a public coordinator URL will be announced when the beta opens Planned . The worker's --coordinator flag points at any coordinator. Format: JSON requests and responses. Authentication: an AI agent uses an agent token on a small set of routes (see agent endpoints ). Contributor endpoints need Authorization: Bearer . You get the token from POST /api/register , and the worker stores it in ~/.config/sparetokens/worker.json . Your provider API key is never part of any request. Transport and headers: use https for any coordinator that is not on your own machine; the worker refuses plain http except for localhost. Every response carries X-Content-Type-Options: nosniff , X-Frame-Options: DENY , Referrer-Policy: no-referrer and a Content-Security-Policy with frame-ancestors 'none' . Errors: a non-2xx response has the body {\"error\": \"message\"} , sometimes with extra fields such as suggestion . Error codes 400 The request is invalid, for example a handle that is not 3 to 24 allowed characters, or a display mode missing its name fields. 401 The contributor token is missing, invalid, replaced by a rotated token, or expired (on a coordinator that sets a token lifetime). An agent token that was revoked or has expired also gets 401. 403 An agent token used a route it may not use, lacks the scope, or is paused by its owner. 404 No such task, account or profile. Anonymous and former accounts have no public profile. 409 A handle is already taken (the body includes a free suggestion ), or you do not hold the lease on a task. 413 The request body or the submitted result is larger than allowed. 408 The request body did not arrive in time. 429 A rate limit was reached (see Retry-After ), too many failed admin token attempts, too many open leases (submit or release one first), too many workers on the account, or too many setup tests this hour. 503 The coordinator is busy. Retry after the number of seconds in Retry-After . Rate limits and size limits The coordinator limits requests per connection and per account with token buckets. A request over a limit gets 429 with a Retry-After header in seconds. An operator can change each value; these are the defaults. Endpoint Per connection (IP) Per account POST /api/register 30 per hour (and 600 per hour for everyone together) not applicable POST /api/tasks/claim 1,200 per minute 120 per minute POST /api/tasks/{task_id}/submit 1,200 per minute 120 per minute POST /api/tasks/{task_id}/heartbeat and POST /api/me/token/rotate none 600 per minute Failed admin token attempts (successful ones are not counted) 10 per hour (and 200 per hour for everyone together) not applicable POST /api/canary 60 per hour 5 per worker per hour Public reads (stats, leaderboard, aggregates, findings, profiles) 600 per minute not applicable Workers and leases: an account may have at most 20 workers. Each worker may hold 3 open leases and each account 10 (429 beyond that). A lease lasts one hour and heartbeats extend it, but never past 6 hours in total; then the task returns to the queue. Agent tokens: each has its own request limit (default 30 per minute, at most 120), holds at most 3 open leases (default 2), and may take at most 100 tasks per day (results plus open leases in the last 24 hours). The account's lease cap of 10 and its other limits apply on top, across all its workers and tokens. An account may have 10 live agent tokens. Request bodies: 64 KB for most requests, about 2 MB for submit (twice the result limit plus 64 KB), and 1 MB for admin requests. A larger body gets 413 before it is read. A client that stops sending a promised body gets 408 after 15 seconds. Results: the resu"}, {"url": "/docs/cli", "title": "CLI reference", "section": "Reference", "text": "The worker installs one command, sparetokens . This reference lists every command and flag, taken from the worker's own command tree. Run sparetokens --help or sparetokens COMMAND --help for the same text on your machine. The worker is not public yet, so these are beta steps. Install today is from a checkout ( pip install . or pipx install . ). Available at launch Install with pipx install sparetokens , Homebrew or the one-line installer; see install . Commands at a glance sparetokens register create your public handle (username) and a contributor token sparetokens link add this machine to your account with a code from your dashboard on sparetokens.ai sparetokens web-link get a one-time code that joins your website sign-in to this computer's account sparetokens login sign in with GitHub (device code; no password goes through SpareTokens) sparetokens run claim tasks and work on them sparetokens status what each source will do next and why, plus registration and which providers are ready sparetokens give choose how a source gives: --fixed, --expiring, --share, --all, --idle (or --leftovers where a provider allows it); writes rules.toml sparetokens boost a one-off boost: give an amount now (boost openai 5) or run for a while (boost mac 2h); it expires sparetokens preview what a source's rule would have done over a week: given, expired and kept (an example week, clearly labelled) sparetokens config show or edit local config (references to credentials, never the credentials) sparetokens profile choose how you appear on the public leaderboard and which fields are public sparetokens setup guided setup in nine steps (safe defaults; Enter keeps them) sparetokens rotate-token replace your worker token (or, with --account, your account token) now; `run` also does this on its own every 30 days sparetokens pause pause donating (all sources), optionally for a while: pause 2h sparetokens remote phone app control: on, off, status, or allow a bounded remote boost sparetokens resume resume donating after pause sparetokens logs show the background service log sparetokens service install, remove or check the background service sparetokens uninstall remove the service, config and local data (asks what to do with your public profile) sparetokens detect list the logins, keys and local model servers found on this machine sparetokens doctor self-check: OS, sandbox, providers found, provider-terms status, config dir and whether the coordinator answers (read-only) sparetokens statusline opt-in Claude Code status line hook that records your plan usage locally sparetokens inspect a task in plain language before it runs: goal, exact prompt, tools, network, budget, checks and signatures sparetokens verify-log download the public task log and check its hash chain, Merkle root and signed head sparetokens report report a task that looks wrong, harmful or wasteful (goes to the public report queue, redacted and shown after review) sparetokens review review mode: be asked before each new task type runs for the first time sparetokens history recent donations from the local ledger; --show TASK prints that task's local transcript sparetokens budget what has been spent today, this week and this month, per source sparetokens agent-token let your own AI agent contribute: create, list, pause or revoke its scoped, expiring token (needs your account token) sparetokens mcp run the local MCP setup assistant (stdio only) so your own AI agent can set SpareTokens up, check status and adjust giving rules sparetokens feedback send a note to the people running the beta, or open a pre-filled GitHub issue (bug, idea or goal proposal) Global option: --version prints the installed version. Command reference sparetokens register Create your public handle (username) and a contributor token. --handle your public username: 3-24 letters, digits, _ or -; shown as typed, unique ignoring case Required. --coordinator Coordinator URL. Default is $SPARE_COORDINATOR, or http://127.0.0.1:8795. Mu"}, {"url": "/docs/glossary", "title": "Glossary", "section": "Reference", "text": "Plain-word definitions of the terms used across SpareTokens. Each term has its own link, so you can point someone straight at one. Short, and in alphabetical order. Looking for what to do? Start with the getting-started guides . Terms Agent token A scoped, expiring token that lets your own AI agent claim and submit tasks under your account. It never carries an API key. You can pause or revoke it at any time. See the agent guide . API key A secret string from your AI provider that lets a program use your account's credit. SpareTokens reads it by name from your environment or keychain and never copies it or sends it anywhere. Beta The invitation-only stage that starts after the private pilot. Invites go out in waves. No date is promised. Boost A one-off gift, such as \"give $5 now\" or \"run for 2 hours\". It replaces your schedule for a while and then expires by itself. It never replaces the protections. Canary The tiny setup test task that proves the whole loop works for your provider: claim, work, submit, verify. It carries no leaderboard weight and is hidden from public pages. Ceiling A hard limit on top of any giving style, such as $20 a month. Required for the everything-spare style on an API key, so giving is always bounded. Circuit breaker The protection that pauses a source after three failed or rejected tasks in a row, for 24 hours. sparetokens config reset-breaker NAME clears it. Coordinator The server SpareTokens runs. It issues signed tasks, receives results, verifies them and keeps the public log. It never runs worker code and never sees your key. Credit Recognition on the leaderboard for verified work, under your username. It is not money, and spend never changes it. Everything spare A giving style that gives whenever the source is free, down to a keep-back of at least 5%. API keys need a ceiling. Expiring credit A giving style for promo or prepaid credit with an end date. The worker paces giving evenly to the date and stops at the floor you set. Fixed amount The default giving style for API keys. Give up to a set amount per day, week or month, as a hard ceiling checked before every task. Floor The amount of expiring credit you always keep for yourself. The worker stops giving when the balance reaches it. Giving style The rule that decides when a source may give and how much: fixed, expiring, share, everything spare, idle, boost or leftovers. See giving styles . Handle (username) The name you appear under, 3 to 24 letters, digits, underscore or hyphen. Real names are shown only if you opt in. Idle time A giving style for local models. The worker runs only when the machine has been idle for a while, is plugged in and is not hot, and stops when you return. Keep-back The share of a source you always keep for yourself. It can never be lowered below 5% for the everything-spare style. Key reference The name of where a key lives, such as env:ANTHROPIC_API_KEY or keychain:ITEM . Rules files hold the name, never the key. Leaderboard The public ranking of contributors by verified work, weighted by task type. Spend never affects rank. Lean A proof assistant. A Lean check compiles a submitted proof in a sandbox and re-checks the required statement, so a proof is accepted without trusting the author. Lease The time a worker holds a claimed task. It returns on its own when the lease runs out, and a worker can hold at most a few at once. Literature check A task that checks the status of a problem against the published literature, with agreeing runs and a referee that quotes the cited papers. Local model A model that runs on your own computer through Ollama, LM Studio or an MLX server. It has no bill per call and costs electricity and time. MCP Model Context Protocol, a standard way for an AI agent to use tools. sparetokens mcp runs a local MCP server for setup and, with an agent token, for claiming and submitting tasks. Preview sparetokens preview NAME simulates the last 7 days under a rule and prints what would have been given, wha"}, {"url": "/docs/troubleshooting", "title": "Troubleshooting and FAQ", "section": "Reference", "text": "Fixes for common problems with the worker. For general questions, see the FAQ . Start with the self-check Run sparetokens doctor . It is read-only and prints your OS, Python version, whether a sandbox is available, which providers it found, the provider-terms status, the config directory and whether the coordinator answers, followed by a short list of anything to look at. Paste its output into a bug report (it never contains a key). Add --offline to skip the network check. \"no working OS sandbox on this machine\" Shell and solver tasks need an OS sandbox, and the worker never runs them without one. Run sparetokens status : the sandbox: line gives the exact reason and the fix. Literature tasks and other model-only tasks still work without a sandbox. macOS: sandbox-exec is built in. If it is missing, the system is unusual or damaged. Linux, \"bubblewrap is not installed\": sudo apt install bubblewrap (or your package manager's equivalent). Linux, \"does not allow unprivileged user namespaces\": common inside Docker and on some hardened hosts. Run the worker directly on the host or in a VM. If you control the container, relaxing its seccomp profile is your decision; the worker will not weaken its own sandbox to start. Linux, \"masks /proc\": a Docker container hides parts of /proc . The same advice applies; --security-opt systempaths=unconfined is the relevant container option. Ubuntu 23.10 and later, \"AppArmor restricts unprivileged user namespaces\": add an AppArmor profile for /usr/bin/bwrap that contains userns, and reload AppArmor. Setting kernel.apparmor_restrict_unprivileged_userns=0 also works but relaxes a protection for the whole machine. Native Windows: there is no sandbox. Use WSL2 as described in the quickstart . To test bubblewrap by hand: bwrap --ro-bind / / --dev /dev --unshare-all --die-with-parent true should exit with status 0. Windows: \"run SpareTokens inside WSL2\" You asked for something that needs a shell or a solver on native Windows. Install WSL2 with wsl --install -d Ubuntu in an administrator PowerShell, open Ubuntu, run sudo apt update && sudo apt install -y bubblewrap python3-venv python3-pip , and install SpareTokens there. Your Windows config is separate from the WSL2 one, so register or run setup again inside Ubuntu. Windows: odd characters or a console error Older Windows consoles use a legacy code page. The worker replaces characters the console cannot show instead of stopping. For clean output, use Windows Terminal or set PYTHONUTF8=1 . \"cannot reach the coordinator\" The worker could not connect. Check the coordinator address with sparetokens config show and, if needed, pass --coordinator URL or set SPARE_COORDINATOR . Planned A public coordinator arrives with the beta. \"the coordinator refused the request\" 401: your contributor token is missing or invalid. Register again, or check worker.json in your config folder ( sparetokens config path shows it). 409 on register: the handle is taken. The error includes a free suggestion. 429: you hold the maximum of 3 open task leases, or you ran too many setup tests in an hour. Finish or release a task, or wait. 413: a result was larger than 1,000,000 bytes. The worker will not start a task Run sparetokens status . It shows whether donation is paused and whether a source was paused by the circuit breaker. A source paused after three failed or rejected tasks stays paused for 24 hours. After you check the cause, run sparetokens resume --breaker NAME (or sparetokens config reset-breaker NAME ). A source paused by reconciliation needs the same reset. Run sparetokens config explain to see what each rule would do right now, and why. A scheduled run respects quiet hours and \"never on battery\". A run you start yourself does not. If a run says a provider is not supported with a subscription login, that is intentional: use an API key or a local model. See provider terms . No tasks match The coordinator only hands out task types your tier can do. Literature tasks need web sea"}]