Docs

Synapse docs

Everything you need to get Synapse running and working for you: from installing it to adding your API key, working with your Bots, and fixing things when they go wrong.

Getting started

Requirements

• A Mac with Apple silicon (M1 or later), on macOS 14 or later.
• About 8 GB of free disk space.
• OrbStack, which runs the Linux computer your Bots work in. It's free for personal use.
• An AI key with some credit on the account: an Anthropic API key from the Anthropic Console, or a key for OpenAI, OpenRouter, Gemini, Mistral or DeepSeek. Or a model on your Mac with Ollama or LM Studio (see Works with).
• An internet connection for setup and while your Bots work.

Install

1. Install OrbStack and open it once.
2. Download Synapse (the .dmg file), open it, and drag Synapse onto Applications.
3. Open Synapse from Applications. The first time, macOS stops it, because Synapse isn't notarized by Apple yet:
   • Right-click Synapse and choose Open, then Open again, or
   • on newer macOS versions, go to System Settings → Privacy & Security, scroll down and click Open Anyway next to Synapse.
   You only need to do this once.

First run

1. The Bots' computer. Synapse starts OrbStack and builds a small Linux computer for your Bots. It downloads about 1 GB, so give it a few minutes. If it stops partway, press Retry.
2. Add your AI key. Anthropic is chosen; paste your Anthropic API key. Or pick another provider, allow it, and paste its key, or pick On this Mac and click Test. Synapse checks the key and tells you plainly if something's wrong. More providers can be added later, in Settings → Account.
3. A quick tour, then pick the tools you use every day and meet your first Bot: start from a suggested one or create your own.

When you first use a feature that needs it, macOS asks for access to the microphone, screen recording or accessibility. Synapse never asks up front.

Your API key

Getting a key

1. Sign in to the Anthropic Console and add some credit under Billing.
2. Open API Keys, create a key and copy it. It starts with sk-ant-.

Adding, changing or removing keys

Open Settings → Account. You'll see your saved keys with most of each hidden. You can keep several named keys per provider, like "Personal" and "Work".

• Add one: click Add key, name it and paste it. The first key is the default.
• Check it: click Test to see whether the key works.
• Choose the default: click Make default. Each Bot pays with the key picked for it in its settings, or the default.
• Cap it: set a Monthly cap. A key at its cap stops its calls and says so.
• Remove it: click Remove. Its Bots move to the default key. With no Anthropic key left, Claude Bots stop until you add one again.

Other AI providers

Your Bots can also run on OpenAI, OpenRouter, Gemini, Mistral or DeepSeek with your own key, or on a local model with Ollama or LM Studio. Pick one in the key step at setup, or later open Settings → Account → Model providers, allow the provider, add its key, then pick a model in a Bot's settings. If you set up without an Anthropic key, new Bots start on your provider's main model, and Synapse's shared work, like the safety reviewer and reading schedules, runs there too; the reviewer asks you until its model passes the safety check. Coding agents and Engineering mode run on the Bot's own model. So do the computer and browser helpers. See Works with.

Synapse reaches Claude with an Anthropic API key only. Signing in with a Claude subscription or a Claude Code login isn't supported.

Using Synapse

Bots

A Bot is a teammate with its own name, look, instructions, memory and skills. Add Bots from the sidebar. Each one keeps its own memory and works on the shared Bots' computer, so several can work at once and hand tasks to each other.

To change what a Bot does, how it looks or what it's allowed to do, open its settings from its chat.

Working with Bots

Talk to a Bot the way you'd brief a colleague: say what you want done and any constraints. Bots break the work into steps, and you can see each step as it happens: files read, commands run, pages visited. They'll send files back to you in the chat, and ask before doing anything risky.

You can add files to a message, and point a Bot at the accounts and tools you connected during setup.

Code

Point a Bot at a repository and describe the change. It works on its own branch in a separate copy of the repo, so it never touches your working files. It runs the tests, then hands back the branch or opens a pull request for you to review.

Voice calls

Press Call in a Bot's chat to talk to it. Your speech is transcribed on your Mac, and the Bot's voice is generated on your Mac as well. If your Mac can't transcribe your language itself, Synapse asks once before using Apple's servers; you can turn that off again in Settings → Voice. Approvals can pop up during a call, so you can say yes or no without leaving it. You can change voices and sound options in Settings → Voice.

Your Mac and approvals

Bots can use your Mac's apps and screen and run commands in a sandbox. Anything risky, such as sending a message on your behalf, stops and asks first:

A card a rule raised names that rule. Always allow on it makes that rule skip this person, site or folder from then on. Make this a rule… and Loosen this rule… open Settings → Rules.

Rules

Write rules in plain English in Settings → Rules, or for one Bot in its settings. A rule is Always allow, Ask first or Never, and can name a Bot, an app or account, a folder, or a person or site. It can also carry a limit: "Ask before anything over $50", "At most 5 sends an hour", "No sends between 22:00 and 07:00" (your time zone). Synapse turns each rule into an exact check, shows it to you with how many of your last 50 actions it would have changed, and enforces it in code. A rule it can't read exactly is refused with the reason. Never beats Ask first, and Ask first beats Always allow.

Start from a preset. Balanced (the default) asks before sends, deletes, payments, uploads to unknown sites, running code from the internet, destructive git, sudo, global installs, app writes, and access or key changes. Careful also asks for sends and app writes you asked for yourself. Hands-off asks only before payments and deletes. A preset sets the preset rules only: Auto-review and Synapse's other built-in checks still run under all three. Presets are ordinary rules you can edit.

Guidelines ("draft, don't send", "cite sources") go to the Bot and to Auto-review as instructions. They aren't enforced like rules.

Some things no rule, preset or mode can change, No limits included: Synapse's own settings, keys and private data; your Mac and your home network (unless you turn on Local network); and the Bots' firewall. In a Bot's settings, Network can limit it to a list of sites; it then can't upload to, or run code from, anywhere else, though it can still read other sites. Synapse's gate enforces this on what the Bot does in the Bots' computer. A per-Bot firewall rule isn't there yet, so a site a script works out as it runs isn't caught.

Mac permissions and the Bots' computer live in Settings → Computer.

Connect Google

Bots can use your Gmail, Google Calendar and Google Drive through your own Google Cloud OAuth client, so nothing goes through a third party. Open Settings → Connected accounts → Google → Set up. The sheet has six steps, each with an Open in browser button for the exact Google Cloud console page and a Copy button for every value.

Do it yourself (about 5 minutes)

1. Create a project.
2. Enable the Gmail, Calendar and Drive APIs.
3. Consent screen: External, the app name, the six scopes the sheet lists, and your email.
4. Publishing status: In production.
5. Create a Desktop app OAuth client.
6. Paste the Client ID and secret, then Connect. Google says it hasn't verified this app: choose Continue, because it's your own app. Then click Allow.

Let a Bot do most of it

Choose Let a Bot do it and pick a Bot that may use the browser on your Mac. It does steps 1 to 5 in the Synapse browser window, where you're already signed in, and each change to your Google Cloud project asks for your OK first. When the client is created, Synapse saves the Client ID and secret straight from the page. The Bot never sees them, and they never appear in the chat.

Why "In production"

Google ends a Testing app's sign-ins after 7 days. In production they last. For your own personal use there's no review: you see the "unverified app" warning once, when you connect.

What always stays with you

If the sign-in ever expires, Synapse shows one Reconnect Google notification. The weekly sign-in check in Settings → Connected accounts is on by default only while your app is in Testing.

Schedules

Bots can do work on a schedule, like a morning inbox brief on weekdays, or when something happens, like an invoice arriving. They tell you what they found. Manage these in Settings → Schedules.

Connect apps with Composio

Composio connects Gmail, Google Calendar, Google Drive, Slack, GitHub, Notion and Linear in one click each, with no Google Cloud setup. You create your own Composio key once. Synapse never uses a shared key.

Create your key in Settings → General → Connected accounts → Composio → Set up:

1. Open Composio opens the Composio dashboard in your browser.
2. Sign in or create a free account, go to Settings → API Keys, create a new key and copy it.
3. Back in Synapse, press Paste key. Synapse reads your clipboard only when you press it.
4. Synapse checks the key with Composio. Key rejected means Composio didn't accept it; copy it again. Can't reach Composio means your Mac is offline or Composio is down; try again later.

Connect Gmail in one click. Open the Marketplace and find Gmail. It offers two ways to connect: Connect directly (your own Google app, the private default) and One click with Composio. Press One click with Composio. Slack, GitHub, Notion and Linear are under Apps through Composio, each with one Connect. The first time, Synapse shows one line about your data (see below) and asks you to accept it. Composio's sign-in page opens in your browser. Approve it there, and the row changes to Connected.

Choose which Bots can use it. A newly connected app starts off for every Bot. Turn it on for a Bot in the list that opens under the app, or in that Bot's settings. You can turn it off again at any time, and it takes effect on the Bot's next action.

What asks. Reading is quiet: a Bot can search and read your mail, events and files without asking. With the default Balanced rules, anything that sends or changes something asks you first, such as sending an email, creating or deleting an event, posting a message or opening an issue. This happens even with Auto-review off. In Full auto, a Bot does what you just asked for without a card, such as the email you told it to send to the person you named. It still asks before deleting, paying, messaging or inviting people you didn't ask it to, acting on many people or items at once, or doing anything an email, web page, routine or another Bot asked for.

Privacy. Apps connected through Composio send their data through Composio. Synapse talks to Composio directly from your Mac with your key; there is no Synapse server in between. Your key is stored encrypted with your other secrets. It never appears in chats or logs, and Bots never see it. Disconnect removes the connection from Composio, and Remove key forgets the key.

Managing Synapse

Spending and budgets

Your Bots use your own keys, so Anthropic, or the provider you picked, bills you for what they use. Synapse meters every model call. Settings → Account shows spend per Bot by day, week and month.

Set a weekly or monthly budget there too. When a Bot reaches it, it pauses or asks you before spending more.

Settings at a glance

Updates

Synapse checks for new versions itself. You can also check in Settings → System → Updates. With Automatic Updates on (the default), it downloads a new version and asks you to restart. With it off, the new version waits in Settings → System → Updates until you download it. Before installing an update, Synapse verifies it was signed with the Synapse release key and signed by the same developer as the app you have. If either check fails, it refuses the update.

Backups

Settings → System → Backups saves your Bots, their memory and settings, and restores them later.

Privacy and your data

The full details are in the Privacy Policy.

• No Synapse account or server. Synapse talks straight to Anthropic, or the AI provider you choose, with your key. The only thing that ever reaches us is feedback you choose to send.
• Your data stays on your Mac, in ~/Library/Application Support/Synapse, and in the Bots' computer (an OrbStack machine called box).
• Secrets are encrypted with a key kept in the app's own data folder. Bots' sandboxed commands can't read it.
• Apps you connect through Composio send their data through Composio, using your own Composio key. See Connect apps with Composio.
• Logs are in ~/Library/Logs/Synapse and never leave your Mac unless you send them.
• This website counts visits with Vercel Web Analytics: no cookies, no personal data, nothing that identifies you. Its fonts are served from this site. It loads release info (the latest version and download link) from GitHub's API, so GitHub sees your IP address for that request. The app itself sends no analytics.
• Feedback leaves your Mac only when you press Send privately or Post on GitHub, and only what its preview shows. Logs are cleaned of keys, tokens, emails and your user name first, and phone numbers, card numbers and addresses in your message are hidden. Replies appear in the app under Your feedback, or at the private link the website gives you. 👍 and 👎 on replies stay on your Mac.

Help

Troubleshooting

macOS says it can't open Synapse

Right-click Synapse → Open, or System Settings → Privacy & Security → Open Anyway. See Install.

Setting up the Bots' computer failed

Check OrbStack is installed and running, and that you have a connection and at least 8 GB free, then press Retry. If it keeps failing, use Settings → System → Setup to repair it.

My API key doesn't work

Use Check in Settings → Account. It tells you whether the key is wrong, the account is out of credit, or you've hit a rate limit. Make sure the key starts with sk-ant- and has credit in the Anthropic Console.

Synapse in two macOS accounts on the same Mac

Supported from version 0.1.1. Each account has its own Bots' computer and its own connection to it. If Synapse ever reaches another account's Bots' computer instead, it tells you.

Something else

Send feedback privately, or open an issue in public, with what you did and what happened. In the app, use Send feedback in the account menu or the Help menu. Settings → System → Diagnostics shows recent errors, and the logs are in ~/Library/Logs/Synapse.

Uninstall

1. Quit Synapse and drag it from Applications to the Trash.
2. To remove your data too, delete ~/Library/Application Support/Synapse and ~/Library/Logs/Synapse.
3. To remove the Bots' computer, open OrbStack and delete the machine called box. Only do this if you don't use a machine with that name for anything else.