DOCS · KEYS & PROVIDERS
You bring the key.
SynthOS is the AI operating system for a company of one, and it runs on a key you supply. You connect your own AI provider account — the model’s thinking is billed by that provider, directly to you, with no markup and no metering from us. The key lives on your Mac, not on our servers. This page is the complete reference for how bring-your-own-key works: which providers fit, how to add and rotate a key, what you pay whom, how to cap your spend, and what to do when a key or a provider returns an error.
WHAT IT MEANS
Your account, your tokens.
Bring-your-own-key means exactly that: you hold an account with an AI provider, you create an API key there, and you give that key to SynthOS. When an agent runs, it calls the provider using your key — so the token usage is yours, billed by the provider on your terms.
No token markup. We do not resell, meter, or add a margin to the model’s usage. The provider charges you for exactly what you used, at the provider’s own published rates. Nothing about that bill passes through us.
The bill stays between you and your provider. Your usage shows up on your provider’s dashboard and your provider’s invoice — not ours. If you have credits, a committed-use discount, or a free trial with that provider, you keep all of it; SynthOS sits to the side of that relationship.
You can use a key you already have. If you’re already paying for an AI provider for other work, the same key powers SynthOS. There’s no separate “SynthOS token” to buy and no wallet to top up on our side.
The distinction that matters: SynthOS is the operator — the cockpit, the agents, the vault, the receipts. The model is the engine you already pay for. Bring-your-own-key keeps the engine on your meter, not ours.
SUPPORTED PROVIDERS
Where to get a key.
SynthOS works with the major AI providers. You create a key in the provider’s own console, copy it once, and paste it into SynthOS. A key is a long secret string — treat it like a password, because it can spend money on your account.
For Claude models, create a key in the Anthropic Console under API Keys, then add billing or credits to the account. Anthropic keys start with sk-ant-. Paste the full string into SynthOS as your Anthropic key.
For GPT models, create a key in the OpenAI platform dashboard under API keys and set up billing. OpenAI keys start with sk-. Paste the full string into SynthOS as your OpenAI key.
You only need a key for the provider whose models you actually use. One provider is enough to run SynthOS; you don’t have to hold keys for all of them. The available models follow whichever key you’ve added.
A key is created in the provider’s console, not in SynthOS — we never see your provider login, and we can’t make a key for you. The provider shows the secret only once at creation, so copy it before you close that screen.
ADDING YOUR KEY
Paste it once, stored locally.
Adding a key takes three steps inside the app. The key is saved on your Mac — not uploaded to our servers — and SynthOS reads it locally when an agent needs to call the provider.
OPEN KEYS & PROVIDERS
Find the key settings
In SynthOS, open Settings and go to the keys and providers section. You’ll see a field for each supported provider, with the status of any key you’ve already added.
PASTE THE SECRET
Enter the key from your provider
Paste the full key string into the field for the matching provider and save. SynthOS validates it with a small test call so you know right away whether the key works, rather than finding out mid-task.
IT STAYS ON YOUR MAC
Stored locally, used locally
Once saved, the key is kept on your machine and used from there whenever an agent calls the provider. You don’t paste it again per task; SynthOS reuses the stored key until you rotate or remove it.
Where it lives: the key is held in your local SynthOS configuration on your Mac. It is not synced to our account system and not part of your vault, so it won’t travel if you back up or share the vault. Moving to a new Mac means adding the key again on that machine.
WHO YOU PAY FOR WHAT
The thinking vs. the cockpit.
There are two bills, and they never mix. Your provider charges you for the model’s thinking — the tokens. SynthOS charges you for the cockpit — the app that turns that thinking into finished work on your Mac. Knowing which is which makes both predictable.
YOU PAY YOUR PROVIDER
The model’s thinking
Every token a model reads or writes — reasoning, drafting, reading your files, planning the steps — is billed by the provider on your key, at the provider’s rates. Heavy days cost more; quiet days cost less. This bill scales with how much you run, and it’s yours to watch on the provider’s dashboard.
YOU PAY SYNTHOS
The cockpit, not the tokens
Your SynthOS subscription pays for the operating system around the model: the agents and parallel crew, the chat, terminal, and browser surfaces, the vault, the receipts and approvals, and the updates. It’s a flat plan, independent of how many tokens you burn — we don’t meter your usage.
Put plainly: pay the provider for the engine, pay SynthOS for the car around it. Because the two are separate, your subscription never moves with a busy week, and your token bill never has our margin on top.
ROTATE & REMOVE
Replace or revoke it anytime.
Because the key is yours and stored locally, you’re always in control of it. Rotating, replacing, or removing a key is something you do in the same keys and providers settings — and, for a true revocation, in the provider’s own console.
To rotate, create a new key in the provider’s console, paste it into SynthOS to replace the old one, and then delete the old key at the provider. Rotating on a schedule is good hygiene; the provider is the only place that can actually retire a key.
To switch accounts or providers, paste a different key into the relevant field and save. SynthOS uses the new key from the next call onward; nothing else about your vault or your runs changes.
To remove a key, clear it in the keys and providers settings. That deletes the stored copy from your Mac, and SynthOS will stop being able to call that provider until you add a key again. To be sure a leaked key can never spend, also revoke it in the provider’s console.
One rule worth repeating: clearing the key in SynthOS removes it from your machine, but only the provider can invalidate the secret itself. If a key may have leaked, revoke it at the provider — that’s the switch that actually cuts off spending.
SPEND CEILING
A hard cap so it never overspends.
Bring-your-own-key means you carry the token bill, so you should set its ceiling. There are two places to do it — a limit at the provider, and the guardrails inside SynthOS — and using both is the safe default.
Set a hard limit at the provider. Both Anthropic and OpenAI let you set a monthly usage limit or budget on the account that owns the key. This is the real ceiling: once usage reaches it, the provider stops accepting calls, so SynthOS physically cannot spend past the number you chose.
Lean on approvals for the risky steps. SynthOS asks before anything consequential and shows a receipt for every action, so long or expensive runs don’t happen silently. You can stop a run, decline a step, and see exactly what each agent did — usage never builds up behind a spinner you can’t read.
Start the cap low. When you’re learning how much a typical day costs, set a deliberately low provider limit and raise it as you get a feel for your own usage. A low ceiling can’t hurt you — at worst a run pauses and you lift the limit.
The honest version: 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 your account. Set that first, then let approvals catch the rest.
TROUBLESHOOTING
When a key or provider errors.
Most key problems come from the provider, not from SynthOS — an expired key, an empty balance, or a hit rate limit. Here’s how to read the common errors and where to fix each one.
An authentication error means the key is wrong, expired, or revoked. Re-copy the key from the provider’s console — watch for a stray space or a truncated string — and paste it into SynthOS again. 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 spend limit. Add funds or raise the limit in the provider’s console. If you set a ceiling on purpose, this is that ceiling working — decide whether to raise it.
A rate-limit error means too many calls hit the provider too fast — common when a large 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, SynthOS has no working key for that provider yet. Add a valid key in keys and providers, confirm it saves without an error, and the matching models will become selectable.
A quick 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 receipt for the failed step shows which one you hit, so you don’t have to guess.
WHERE TO GO NEXT
Your key in, your work out.
You bring the key; SynthOS does the rest on your Mac. Read the concepts behind it, install the app, or see how a vault becomes a product you can share.
Bring your own key · No token markup · Stored locally on your Mac.