Home / Docs / Limits and protections
Limits and protections
Keep-back, ceilings and caps checked before every task, which limit wins, and the always-on protections that keep you in control.
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_usdandper_day_usd, plus token versions,max_turnsandtimeout_s, all with sensible defaults. Set them inrules.tomlor withsparetokens config set-rule. - Schedule:
hours(only between these times) andquiet_hours(never between these). - Run budget:
--budget-usdbounds a whole manual run and each task in it. For providers that do not report dollars, use--token-budgetor--time-budget-mintogether 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 statusshows paused sources, andsparetokens resume --breaker NAME(orsparetokens 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 inrules.tomlor the config, and a value shaped like a key is refused. - Outgoing scan
- Before anything is submitted, the result, artifacts and usage are checked for credential-shaped strings (API keys, access and refresh tokens, JWTs, cloud and repository tokens) and for the actual values of your API-key environment variables. A match blocks the submission locally and the task is released.
- Sandboxed shell
- Shell access is off unless you pass
--allow-bash, and then it runs in an OS sandbox with no network, reads limited to system directories and the task directory, writes limited to the task directory and credentials scrubbed from subprocess environments.
Limits on the coordinator
The coordinator also protects itself and everyone's share of the queue: per-connection and per-account rate limits on registration, claiming, submitting and heartbeats (with 429 and Retry-After), at most 20 workers and 10 open leases per account, request body caps, and a result size cap. The exact numbers are in the API reference.
For the full picture of how the worker is isolated, see the security model.
Edit this page on GitHub: available when the repository opens.