SpareTokens

Home / Docs / Phone companion

Phone companion

Install the SpareTokens phone app on iPhone or Android, see how your computers are giving, pause or boost them, and turn on optional notifications. The phone does not run tasks.

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 plain, and there is never marketing in it.

Privacy and security

  • The app is part of the website: the same session cookie, and every change needs your session and a CSRF token.
  • The app never stores account data on your phone. The only thing kept in browser storage is whether you dismissed an install hint. The service worker caches only the app's own icons, fonts, styles and script, and never any account page or API response.
  • The phone is a companion, not a worker: it holds no API keys and runs no tasks.

Offline

With no connection the app shows a short offline page. Your computers keep giving under their own rules while the phone is offline.

Troubleshooting

A worker shows "No status yet"
Update the worker and make sure the background service is running (sparetokens service install). Status reports come from the service.
A worker shows offline
It has not reported for about ten minutes. The computer may be asleep or off, or remote control may be switched off (sparetokens remote status).
Boost is greyed out
No worker has allowed a remote boost. See the command above.
No notification prompt on iPhone
Add the site to your Home Screen and open it from there. Safari tabs cannot receive web push.

Why not a native iOS app that does some of the work? We looked into whether an iPhone could run small checks itself while charging. The short answer is that Apple's background limits and App Store rules make it a poor fit for now, so the phone stays a companion.

Edit this page on GitHub: available when the repository opens.