DOCS · TROUBLESHOOTING
When something doesn’t run.
Most problems in SynthOS have a plain, local cause — a key the provider rejected, a run that couldn’t fire because the Mac was asleep, an endpoint that’s offline because the app was closed. SynthOS is the AI operating system for a company of one, and it runs on your machine, so the fix is usually close at hand. This page walks the common issues, what each one really means, and where to put it right — and points you to the audit trail when you need to see exactly what happened.
PROVIDER & KEY ERRORS
Invalid key, rate limit, wrong provider.
Because SynthOS runs on the key you supply, most “it won’t run” moments are really the provider answering on your key. The good news: the receipt for the failed step names which one you hit, so you can fix it in the right place instead of guessing.
An authentication error means the key is wrong, expired, or revoked. Re-copy it from the provider’s console — watch for a stray space or a truncated string — and paste it back into SynthOS. If you rotated recently, make sure you’re using the new key, not the retired one.
A billing or quota error means the account behind the key is out of credit or has hit its own limit. Add funds or raise the limit in the provider’s console. If you set that ceiling on purpose, this is it working — decide whether to raise it.
A rate-limit error means too many calls reached the provider too fast — common when a wide crew runs in parallel. It’s usually temporary: wait and retry, run a smaller batch, or ask the provider to raise your account’s rate limit.
If no models appear, or a model you expect is missing, SynthOS has no working key for that provider yet. The available models follow whichever key you’ve added — add a valid key for the right provider, confirm it saves without an error, and the matching models become selectable.
# triage: an auth error is fixed in SynthOS (re-paste the key). # a billing or rate error is fixed at the provider (add credit, # raise a limit, or wait). the failed step’s receipt tells you # which of the two you hit, so you don’t have to guess.
Read Keys & Providers — Bring Your Own KeyAGENTS WON’T START
Not starting, or sitting stalled.
When a crew seems stuck, it’s rarely broken — it’s usually waiting. Either there’s no working key to call, an agent is paused on an approval you haven’t answered, or the job needs more parallel slots than your tier runs at once and the extra pieces are queued.
Check the key first. An agent can’t run without a model to call. If nothing starts at all, confirm a valid provider key is added and saved — a missing or rejected key looks like a crew that never gets going. The receipt will show a provider error if that’s the cause.
Look for an agent waiting on you. SynthOS asks before anything risky. If one card is paused asking for approval, the run waits on that decision — answer it (or decline it) and the crew continues. A pause is the surface working, not a hang.
It may be a tier limit, not a stall. How many agents run at once is set by your plan. When an ask needs more pieces than your tier can run together, the extra ones queue and start as slots free up — nothing is dropped, only ordered. A big job on a smaller plan moves in waves rather than all at once.
Use the kill-switch to reset. If a run is truly wedged, stop it. You can halt a single agent or the whole crew at any moment; stopping ends the work in flight and keeps the receipts of everything that already ran, so you can see where it ended and start fresh.
Stalled almost always means waiting — on a key, on your approval, or on a free slot. The receipts show which, and the kill-switch resets it.
Read Terminal & Agents — dispatch, tiers, and the kill-switchSCHEDULED RUNS
A run that didn’t fire.
SynthOS runs on your Mac, so a scheduled run needs your Mac to be awake when the time comes. The most common reason a run was skipped is simple and honest: the machine was asleep. This is the one limit worth committing to memory.
The Mac must be awake — app-closed is fine, asleep is not. A scheduled run fires from your machine, so the machine has to be powered on and awake at the scheduled time. The SynthOS window being closed is fine; the Mac being asleep, lid shut, or shut down is not — there’s nothing running to start the job.
Keep it from sleeping for the run to land. If you schedule runs for times you’re away from the keyboard, make sure the Mac won’t sleep then — adjust your energy settings, keep it plugged in and lid-open, or keep it awake by your usual means. SynthOS can’t wake a sleeping machine for you; it can only run when the Mac is already awake.
A missed time is skipped, not stored up. If the machine was asleep at the scheduled moment, that occurrence is simply missed — it doesn’t silently pile up and all fire at once when you wake the Mac. The next scheduled time runs normally once the machine is awake again.
Confirm it actually ran in the receipts. To check whether a scheduled run fired, look at the audit trail for an entry at that time. No entry means it never started — almost always because the Mac was asleep — rather than a run that failed halfway.
# honest by design: SynthOS runs locally, so it can only act while # your Mac is awake. closing the window does not stop a schedule. # sleeping or powering off does. there is no cloud machine running # your jobs while the Mac is off — that is the local-first trade.
Read Scheduling — how recurring runs workFORGE ENDPOINT
Showing offline or reconnecting.
The Forge lets you forge a vault into a live MCP endpoint, served from your Mac. Because it’s local-first, the endpoint is live only while your machine is on with SynthOS running — so “offline” usually means the host went away, not that anything is broken. It comes back on reopen.
The endpoint lives on your Mac. When you forge a vault into a product, the live MCP endpoint is served from your machine — it is not a copy hosted somewhere on our servers. That means it’s available exactly when your Mac is, and unavailable when it isn’t.
“Offline” means the host is away. An endpoint that shows offline almost always means the app was closed, the Mac is asleep, or the machine is shut down or off the network. Nothing is corrupted — there’s simply nothing currently answering at that address.
It comes back on reopen. Reopen SynthOS on a Mac that’s awake and on the network, and the endpoint comes back up. “Reconnecting” is the normal in-between state while the host returns — give it a moment after the app is running again rather than re-forging.
For steady uptime, keep the host up. If something else relies on the endpoint staying reachable, the endpoint can only be as available as the Mac serving it — keep that machine awake, on the network, and running SynthOS. Local-first means you hold the keys; it also means you hold the uptime.
A Forge endpoint is live exactly when your Mac is on with SynthOS running. Offline means the host stepped away; reopen, and it returns.
Read about the ForgeBROWSER ACTIONS
Blocked, waiting, or stuck.
When the browser an agent drives appears stuck, it’s usually paused on purpose — waiting for an approval, a login, or your call on a sensitive site. SynthOS holds the consequential steps for you rather than barrelling through them.
An agent that’s about to do something consequential in the browser — submitting a form, making a purchase, changing an account — pauses and asks first. If a browser step looks frozen, check whether a card is waiting on your approval, then approve or decline it to continue.
A page that needs you signed in will stop the agent until the login is handled. Sign in yourself when prompted — your credentials stay yours and aren’t something the agent guesses. Once you’re through the login, the agent picks the task back up.
On sensitive destinations — banking, payments, anything that can spend money or change important settings — the agent is deliberately cautious and will hand control back to you for the critical action. That hand-off is a guardrail, not a failure.
If nothing is waiting on you and the page genuinely won’t progress — a site that blocks automation, a CAPTCHA, a page that never loads — stop that agent with the kill-switch. The receipts show where it stopped, so you can finish that step by hand or take a different route.
# a stuck browser is usually a waiting browser. approvals, logins, # and sensitive sites all pause on purpose — that’s the loop you # stay in. when a site simply won’t cooperate, the kill-switch # stops the agent and the receipts show exactly where it ended.
Read Browser — how SynthOS drives the webSPEND CEILING
When a run hits the cap.
If a run stops and tells you it reached a spend limit, that’s the ceiling doing its job — protecting the token bill on your own provider key. The question is only whether to raise the cap, and where the real limit lives.
Stopping is the feature, not the fault. A run that halts at the cap did exactly what you asked of it: it didn’t quietly run up a bill. SynthOS asks before anything consequential and shows a receipt for every action, so a long or expensive run doesn’t happen behind a spinner you can’t read.
Raising the cap is deliberate. If the work is worth more than the current ceiling, raise the limit and let the run continue. Treat that as a decision, not a reflex — the ceiling is low precisely so a surprising cost pauses for you rather than clearing itself.
The hard limit lives at the provider. SynthOS can warn, ask, and show receipts, but the only thing that can guarantee a dollar figure is never exceeded is the provider’s own hard limit on the account that owns your key. Set that first; then let approvals catch the rest.
Start the cap low and learn your usage. While you’re getting a feel for what a typical day costs, keep the ceiling deliberately low and lift it as you go. A low ceiling can’t hurt you — at worst a run pauses and you raise the limit.
# the honest version: SynthOS warns, asks, and shows receipts, but the # guaranteed dollar ceiling is the provider’s hard limit on your # account. hitting the cap means it worked — decide whether to raise it.
Read about setting a spend ceilingTHE AUDIT TRAIL
See exactly what ran, and why.
Almost every question on this page is answered by the same thing: the receipts. SynthOS keeps a full local audit trail of what ran, when, and what it returned — so diagnosing an issue is reading the record, not guessing at a black box.
Every action an agent takes leaves a receipt — the command and its result, the browser step, the provider call, the approval you granted or declined. Scroll back through a run after it finishes and the whole transcript is there in order. There is no separate “debug mode” to switch on: the honest record is the default view.
The rows above are an illustration of the receipts, not a live trail. In the app each entry carries the real command, result, and time.
That record is how you tell apart problems that look the same from the outside. A scheduled run with no entry at all never fired — the Mac was asleep. A run with an entry that stops at a provider error is a key or billing issue to fix at the provider. A run that pauses on an approval is waiting on you. A run that halts at the ceiling hit your spend cap. The trail turns “it didn’t work” into a specific line you can act on.
# the receipts are the source of truth. no entry → it never started. # entry + error → fix where the error points (provider, login, site). # entry + waiting → it needs your decision. entry + stopped → cap or # kill-switch. read the line, then fix the thing it names.
Read Security & Privacy — receipts, approvals, and local-firstGETTING HELP
Still stuck? We’ll help.
If you’ve read the receipts and the cause still isn’t clear, get in touch. Tell us what you asked for, what the audit trail shows, and where it stopped — the more of the record you share, the faster we can pin it down.
Local-first · Bring your own key · A receipt for every action · [email protected]