DOCS · CORE CONCEPTS
Four ideas, and the rest is elaboration.
SynthOS is the AI operating system for a company of one. Almost everything in these docs is a detail of four mental models: you direct and agents execute, those agents run in parallel, their work files into a vault you own, and a receipt and an approval keep you in charge of every step. Learn these four and each surface, tool, and setting in the rest of the docs becomes obvious.
THE OPERATOR MODEL
You direct. Agents execute.
You say what you want in plain language. SynthOS decides how — it picks the tools, sequences the steps, and does the actual work. You operate; you don’t implement.
YOU STATE THE OUTCOME
Describe the result, not the recipe
A request is the outcome you want in your own words — “pull last month’s invoices into a summary,” “set up the repo and open a draft PR.” You don’t name commands or wire up steps. The intent is the input.
IT CHOOSES THE TOOLS
The system plans the path
SynthOS reads the request, decides which of its built-in tools fit, and orders them into a plan — running command-line tools, driving the browser, editing files, creating assets. The same ask can take a different path as your vault and context grow.
IT DOES THE WORK
Real actions, not a to-do list
Each step runs on your Mac and shows up as a card you can read — the command, the result, the file that changed. It does the work and hands you the outcome, not homework. When something is risky, it stops and asks first (see receipts and approvals).
The mental shift: you move from doing the steps to specifying the result and reviewing the work. Direction in, finished work out — with a record of everything in between.
AGENTS & PARALLELISM
One ask becomes a crew.
An agent is a worker the system spins up to carry out part of a request. A single ask rarely needs just one. SynthOS can split the work into several agents and run them side by side on your Mac.
An agent is a single worker with a job: research a topic, refactor a file, fill in a form, draft a document. It uses the same tools you have access to and reports back what it did.
When a request has independent parts, SynthOS runs several agents at once — a crew working in parallel rather than one worker grinding through a queue. Three sources researched together; several files edited at the same time.
That parallel work happens on your Mac, using your provider key. The model does the thinking; your machine runs the tools, holds the files, and keeps the receipts. Nothing is farmed out to a server you don’t control.
You see each agent as its own stream of cards, so a crew of five is still legible — you can follow, pause, or step in on any one of them.
THE VAULT
A company brain you own.
The vault is where the work lives and accumulates. It’s plain Obsidian-compatible markdown on your disk — auto-linked into a live graph that compounds instead of resetting every session.
Markdown on disk, not a database. Everything agents produce — notes, summaries, plans, drafts — is written as ordinary markdown files in a folder you choose. You can open them in Obsidian, a text editor, or any tool that reads files, with or without SynthOS running.
Auto-linked into a live graph. As notes reference each other, SynthOS connects them into a graph you can watch grow — the same wiki-style links Obsidian uses. The structure emerges from the work; you don’t have to file anything by hand.
It compounds. Because the vault persists between sessions, each request can build on what came before instead of starting from a blank context. Your company brain gets denser and more useful the more you run — it doesn’t reset.
You own it, fully. The vault is your files, in your filesystem. Back it up, sync it, version it in git, or move it to another machine — it’s yours, and it stays readable without us.
The vault is the difference between a chat that forgets and an operating system that remembers. It’s the asset the work leaves behind.
RECEIPTS & APPROVALS
You stay in charge.
Autonomy without oversight is just risk. SynthOS asks before anything consequential, records a receipt for every action, and keeps a full local audit trail of what ran and why.
Before a step that’s hard to undo — deleting files, spending money, sending something out, running a destructive command — SynthOS stops and asks. You approve or decline. Routine, reversible work proceeds; the risky moves wait for you.
Every action leaves a receipt: what tool ran, what it was given, and what it returned. The work is never a black box — each card is a record you can read after the fact, not just a spinner that finished.
Those receipts add up to a local audit trail of everything SynthOS has done on your machine — what ran, in what order, and why. It lives on your Mac, so you can review a run, see what an agent touched, and trace any change back to the request that caused it.
Guardrails are part of how SynthOS works, in every tier — never a paid add-on. This is the honest version of “autonomous”: it acts on its own, but it shows its work and asks before it crosses a line you set.
BYO-KEY & LOCAL-FIRST
Your keys. Your data.
SynthOS runs on a key you bring and data that stays on your machine. Two principles, one promise: you control what powers it and where it lives.
Bring your own provider key. You connect your own AI provider account, and the usage bill stays between you and that provider — no token markup from us. Your key is stored locally on your Mac, not on our servers.
Local-first by default. Your vault, your run history, and your credentials live on your Mac. The work happens on your machine; we’re not a middleman holding your files or your keys.
What sign-in is for. You sign in only to sync and manage your plan — not to route your work through us. The account handles billing and your download; the operating part runs locally against your own key.
The model still runs in your provider’s cloud, because that is where the model is — local-first means your data, keys, and history stay on your Mac, and the only thing leaving it is the request you chose to send.
SURFACES VS. TOOLS
Three surfaces over forty-eight tools.
It helps to separate where you watch the work from what does it. The surfaces are the three windows you read; the tools are the built-in moves underneath them.
The chat, terminal, and browser are the three surfaces — the views where the work becomes visible. Chat is where you ask and watch steps stream in; the terminal shows the command-line SynthOS drives for you; the browser shows the web it operates. You read the work as it happens.
Beneath the surfaces are the 48 built-in tools — the concrete moves an agent can make: run a command, edit a file, open a page, fill a form, create an asset, ask for approval. You never call them by name; the system chooses the right tool for the outcome you described.
In short: you talk to a surface, the system reaches for a tool. The rest of the docs walks each surface and the tools beneath it in detail.
WHERE TO GO NEXT
Now see them run.
You have the four models. Next, watch the surfaces in action and read how each capability is built on top of them.
Forge a vault into a live MCP endpoint · Bring your own key · Local-first.