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 system that gives every asset its own AI Computer, 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 record of 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 entry 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 record will show a provider error if that’s the cause.
Look for an agent waiting on you. The agent checks in before consequential steps. 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.
Stop the run to reset. If a run is truly wedged, stop it. Stopping is scoped to the run you are watching — it ends the work in flight and keeps the record of everything that already ran, so you can see where it ended and start fresh. There is no one control that halts every agent at once.
Stalled almost always means waiting — on a key, on your approval, or on a free slot. The record shows which, and stopping that run resets it.
Read Terminal & Agents — dispatch, tiers, and stopping a runSCHEDULED 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 record. 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 trade for running # on your own hardware.
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 your machine answers the calls, the endpoint is live only while it 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. Serving it yourself 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 run. The record shows 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, stopping that run # ends it and the record shows exactly where it ended.
Read Browser — how SynthOS drives the webWHEN A RUN COSTS MORE THAN YOU EXPECTED
Where the real limit lives.
A long run on your own provider key can cost more than you meant to spend. SynthOS shows you that as it happens and lets you stop the run you are watching — but the limit that actually cannot be exceeded is the one you set at your provider.
Watch it while it runs. A run reports what it is spending as it goes, so an expensive run doesn’t happen behind a spinner you can’t read. If the number is climbing faster than the work is worth, that is your signal.
Stop the run you are watching. Stopping is scoped to that run and takes effect the moment you ask for it. The record keeps everything that already happened, so you can see exactly where it ended and what it cost to get there.
The hard limit lives at the provider. The only thing that can guarantee a dollar figure is never exceeded is your provider’s own hard limit on the account that owns your key. Set that first. It is the one limit that cannot be talked out of stopping, and it is the one we point you at instead of inventing our own.
What we don’t have. There is no in-app spend ceiling you set, and no single control that halts every agent at once. Both used to be described on this site; neither is in the app, so neither is documented here. When they ship, this page changes.
# the honest version: synthos shows per-run spend and stops the run # you’re watching. the guaranteed dollar ceiling is your # provider’s hard limit on your account — set it there.
Read Keys & Providers — where your key lives and who bills itTHE AUDIT TRAIL
See exactly what ran, and why.
Almost every question on this page is answered by the same thing: the record. 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 an entry — 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 record, 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 marked stopped was stopped — by you, or by the provider refusing the call. The trail turns “it didn’t work” into a specific line you can act on.
# the record is 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 → you # stopped it, or the provider did. read the line, then fix what it names.
Read Security & Privacy — the record, check-ins, and what syncsGETTING HELP
Still stuck? We’ll help.
If you’ve read the record 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.
Private cloud sync · Bring your own key · A local record of what ran · [email protected]