DOCS · THE FORGE · EARLY ACCESS
Forge your vault into a product.
FORGE is the SynthOS surface that turns a private knowledge vault into something other agents can call. The vault is yours and stays private by default; FORGE lets you open a narrow, scoped, revocable window onto it — either as a live endpoint on the network or as a bundle that runs only on a machine you choose. This page documents how it actually behaves today, and is explicit about the parts that are still on the roadmap. FORGE is in early access, so read the roadmap section as a promise of direction, not of dates.
TWO SHAPES, ONE VAULT
Forge a vault into a live MCP endpoint.
A forged vault takes one of two shapes. Both read from the same vault, under the same scope rules — you pick the shape that fits who needs to reach it.
Forge an MCP server when something should be callable at an address. You get a live endpoint that any agent can call — a client’s agents, your own agents in other tools, anything that speaks the Model Context Protocol. It exposes a fixed read surface over the vault you chose, and nothing else.
Forge a CLI when access should stay on a machine. You get a one-line bundle you run locally — no address, no network listener. It reads the same vault under the same scope rules, but the calls never leave the machine it’s installed on.
Same vault, same scope, same revoke. You can forge both from one vault if some callers need an address and others should stay local.
WHAT SHIPS TODAY
Read-only by default.
Everything in this section is shipped and behaves exactly as described in the current early-access build. A new forge starts locked down: it can read, and nothing else.
A FIXED TEN-TOOL READ SURFACE
Ten read tools, and no writes
A new forge defaults to read-only: a fixed set of ten read tools — reading, listing, searching, and following links through the vault you chose. The set is fixed, not arbitrary: there is no tool in it that writes, deletes, or runs anything. The full list is visible before you forge and any time after.
TOKEN-GATED
The token is the key
Every forged endpoint is token-gated. A caller needs both the address and a token to reach it — the address alone resolves to nothing. Nothing is listed publicly and there is no directory; the endpoint doesn’t exist at all until you forge it, and isn’t reachable until you hand someone a token.
REVOCABLE IN ONE CLICK
One click, and it’s gone
Pulling a forged product is one click, and it’s immediate. Revoke a token or pull the whole endpoint, and the address stops resolving the moment you confirm — there is no propagation window to wait out and no cached copy left serving.
LOCAL-FIRST
Your Mac serves the calls
FORGE is local-first: your Mac serves the calls. Nothing is mirrored to a server we run — the vault, the read surface, and the answers all live on your machine. That is also why an endpoint is only reachable while your Mac is on with SynthOS running (see how status works, below).
Read-only means read-only. The ten-tool surface has no write path, so a caller — even a misbehaving one — cannot change, delete, or run anything in your vault through a forged endpoint. The strongest thing a token can do is read what you scoped it to.
THE READ SURFACE
What the ten tools can do.
The read surface is a fixed set of ten tools. They cover four moves over the vault you chose — read a note, list what’s there, search the text, and follow the links between notes. The exact, authoritative list is shown in the app before you forge; this is the shape of it.
- 01Read the contents of a single note.
- 02List the notes and folders in the vault.
- 03Search the full text across the vault.
- 04Follow links out of a note to the notes it references.
- 05–10Six more read tools in the same family — resolving titles, reading metadata, and walking the graph — all read-only, none that write. The exact set is enumerated in the permissions sheet before you forge and any time after.
The set is fixed by design: you scope which notes a token can reach, not which tools exist. There is no setting that adds a write tool to a forged endpoint.
HOW STATUS WORKS
Live, offline, or reconnecting.
Each forged product shows a status — live, offline, or reconnecting. That status is computed from live signals, never cached. It tells you the truth about reachability at the moment you’re looking.
Computed from live signals, never cached. The status light reflects whether the endpoint is actually reachable right now — it is derived from the live connection, not read from a stored value that could be stale. When the app says live, it is live; when it says offline, it never pretends otherwise.
Offline is honest, not broken. Because FORGE is local-first, an endpoint goes offline when your Mac is asleep, off, or SynthOS isn’t running — there is no always-on server standing in for it. reconnecting is the in-between: the app is re-establishing the connection.
Endpoints come back on their own. A live endpoint that went offline doesn’t need to be re-forged. When you reopen the app, it reconnects and comes back at the same address with the same scope — you don’t hand callers a new token after a restart.
The honest consequence of local-first: a forged endpoint is reachable exactly as often as your Mac is on with SynthOS running, and the status light says so. Always-on hosting is on the roadmap — until then, “live” means “live on your machine, now.”
SCOPE & TOKENS
You gate by token.
Access is controlled by tokens and scope. A token is the key; the scope is what that key can read. The two settings — who holds a token, and what the endpoint exposes — are what you change over the life of a forged product.
You gate by token. Anyone holding both the address and a token can call the endpoint — which means exactly the people you gave them to. Hand a token to a client; pull it when they should no longer have access. There is no anonymous access and no public listing.
You can change what’s shared after it’s live. Open the product, edit its permissions, and the new scope applies from the next connection — a caller that’s mid-session keeps the scope it connected with until it reconnects under the new one. Scope edits are forward-looking by design.
Revoke is immediate. Unlike a scope edit, a revoke doesn’t wait for the next connection — the moment you confirm, the token stops working and the address stops resolving. If access needs to be gone now, that’s what revoke is for.
The distinction worth remembering: a scope edit narrows or widens what an endpoint exposes from the next connection; a revoke ends access now and the address stops resolving. Use the first to adjust, the second to cut off.
ON THE ROADMAP · NOT YET SHIPPED
Coming, not shipped.
The items below are roadmap. They are not in the current build, and this page will not describe them as if they were. They are listed here so you know where FORGE is headed — not so you can rely on them today.
Per-call metering. Counting and recording each call to a forged endpoint, so usage can be measured. Not shipped yet — today access is binary: a token works or it’s pulled.
Pricing and payouts. Charging for access from inside the product — prices, billing, and payouts to the publisher. Not shipped yet. You can gate access today by deciding who holds a token, but money doesn’t flow through FORGE; that part is roadmap.
An opt-in directory. A place to list a forged product so others can discover it — strictly opt-in. Not shipped yet. Today there is no directory at all and nothing is listed publicly; an endpoint is only known to the people you hand a token to.
If a capability isn’t in the “what ships today” section above, treat it as not present. Per-call metering, pricing, payouts, and the opt-in directory are coming — not shipped — and this page will move them up the moment they are real.
FORGE FAQ & THE FULL FORGE PAGE
The whole picture, in one place.
The canonical Forge page carries the full FAQ — what an endpoint exposes, who can call it, changing scope while live, behavior when your Mac is asleep, and MCP versus CLI — with answers kept in step with the structured data.
Read-only by default · Token-gated · Revoked in one click · Local-first, on your Mac.