Guides
Local-First AI Agents: Why Where Your Agent Runs Matters
Where an AI agent runs decides who holds your files, logins and bills. What stays on your Mac with Brainwrite, and what still goes to your AI provider.
A local-first AI agent keeps its workspace on your computer: conversations, files, memory and saved state. That matters for three reasons. It decides who holds your data, where your logins live, and who bills you. It does not mean nothing leaves your machine. If a bot uses a cloud model, what it sends to that model goes to the provider.
Why does it matter where an AI agent runs?
An agent is more than a chat box. It reads files, calls apps, runs commands and keeps notes between sessions. Each of those leaves something behind: a transcript, a token, a cache, a log. The question is where those pieces live and who can reach them.
There are roughly three places an agent can run:
| Where it runs | Who holds the workspace | Typical trade-off |
|---|---|---|
| A vendor's hosted service | The vendor | Nothing to install, but your history and app connections sit in their system |
| Your own computer | You | Your data stays with you, but the computer has to be on |
| Your own server or cloud machine | You, on hardware you rent | Always on, but you choose and manage that machine |
Brainwrite is built for the second and third rows. The desktop app runs on your Mac. If you want bots running while your Mac sleeps, Brainwrite Cloud gives you your own always-on computer rather than a shared hosted service.
What stays on your machine with a local-first agent?
In Brainwrite, these stay on your computer:
- Chats and threads. Every conversation and its history.
- Files. Each bot's working folder, and anything it writes there.
- Memory. Each bot's memory is plain text you can read, edit and delete. It is not a hidden profile.
- Agent state. Sessions, settings and the record of what ran.
- Secrets. Tokens you save as secrets sit in your operating system's secure store.
Dictation also stays local. The composer microphone uses Apple's on-device speech recognition, so your voice is not sent anywhere to be transcribed.
What still leaves your computer?
This is the part local-first marketing tends to skip. Here is the honest list.
Your prompts go to your AI provider
Brainwrite does not run the model. It starts the agent command-line tools you already have installed, such as Claude Code or Codex, and those tools talk to their provider. When a bot reasons about a file, the relevant text goes to that provider. The provider's own terms decide how it is handled, retained and billed. Read them for any provider you connect.
If a task should not reach a cloud model at all, give that bot a local model. Brainwrite supports local models through OpenCode, with runtimes such as Ollama or LM Studio. The Brainwrite docs suggest exactly this: a local-model bot for private or offline work.
Connected apps talk to their services
When a bot reads Gmail or posts to Slack, that request goes to Gmail or Slack. Brainwrite connects apps through Composio. You sign in with OAuth in your browser, and the OAuth tokens stay with Composio. They are never written into bot prompts. See connected apps.
Your account check goes to Brainwrite
Brainwrite's account service sees your email and your plan. The app checks it when it opens and every 8 hours. It does not receive your chats or files.
How does a local-first agent handle credentials?
Credentials are where location matters most. A hosted agent service usually holds your app tokens and model keys on its servers. A local-first agent keeps them closer to you, but it still has to handle them carefully on your machine.
Brainwrite separates them like this:
| Credential | Where it lives | Who sees the value |
|---|---|---|
| AI provider login | The agent CLI's own login on your computer | Only the process for that provider |
| Connected app OAuth tokens | Composio | Never placed in prompts |
| Skill tokens saved as secrets | Your OS secure store | Inserted only when a request is sent, only to one https site |
| Custom MCP server headers or env values | Brainwrite's write-only settings | Never shown again after saving |
A few details matter here. Provider credentials are injected only into the process that needs them, so one agent does not inherit another provider's keys. The app's interface only learns whether a credential is configured, not its value. A secret is sent only to the one site you allow, redirects are never followed, and responses are scrubbed of the token before the bot sees them. The security page covers the full model.
One caveat from the docs: Brainwrite assumes the logged-in operating system user owns the workspace. On a shared Mac, other administrators may be able to read app data. Use a separate OS account if that matters to you.
How does running locally affect AI agent costs?
Location also decides who sends you the bill.
- Brainwrite's plan covers the app, and on Brainwrite Cloud, the always-on computer. It does not include AI usage. See pricing.
- Your AI provider bills model usage on your own subscription or API key, under its own limits.
- Local models cost you hardware and electricity, not per-token fees.
Because you bring your own model, you can see and control spending. Each thread shows its token use, split into uncached input, cached input and output, plus cost when the provider reports it. See usage and cost. You can also give an expensive bot a cheaper model, or move a routine job to a local model.
What is the catch with running AI agents locally?
The main one is uptime. A local app only works while it is running.
- Routines need the app open. A routine that falls due while Brainwrite is closed does not run on your Mac. Your Mac has to be awake for local routines.
- Webhooks need the app open. The local webhook receiver stops when you quit the app.
- Offline has limits. The app keeps working for up to 7 days without reaching the account service, but cloud-model bots still need their provider.
Brainwrite Cloud answers the uptime problem without moving to a shared service. It is your own Linux computer with 2 shared vCPUs, 2 GB of RAM and 30 GB of storage, running your bots around the clock. Connecting the desktop app to your Cloud does not copy or upload the chats, files or AI accounts on your Mac. You sign in to your AI provider there separately. The Cloud docs explain the setup.
How to decide what should run where
A short rule of thumb:
- Sensitive files, local tools, your own logins: run the bot on your Mac.
- Work that must not reach a cloud model: give the bot a local model.
- Scheduled or overnight work: run it on Brainwrite Cloud, or keep your Mac awake.
- Risky browser or desktop work: use an isolated local VM instead of your own desktop.
Try it
Brainwrite runs on macOS today. Download the app, then choose a plan on the pricing page. Start with one bot, one working folder, and the AI account you already use, then read the security overview before you connect your inbox.
