# Marfa's architecture (/build/architecture)

The parts of Marfa and how they fit together, from the instance that holds a person's data to the apps, agents, devices and connectors that reach it.



Marfa has one center, the **instance**, which holds everything a person keeps: their files and pictures, their notes and bookmarks, and what they keep in other services. Everything else is a program outside it that reaches it over its HTTP API, with a credential that reaches only what the owner allowed.

## The instance [#the-instance]

An instance is one running Marfa server and the data it keeps, in one SQLite database and a folder of files. It belongs to one person, its **owner**, and runs on their own Mac or server. [Install Marfa](/run/install) shows how to run one.

**The instance is the source of truth.** Apps, agents, devices and connectors read from it and write to it, and never talk to each other. When two of them change the same thing, the instance decides the outcome, and every copy comes into line with it.

## The data [#the-data]

Everything in an instance is an **item**: one file, photo, note, bookmark, contact or conversation. Its **type**, such as `core.file.image` or `core.note`, says which properties it holds, and Marfa checks every write against it, so every app that reads an item knows what its type requires. [Items and types](/build/items-and-types) explains both.

Around its properties, an item carries more:

* **Tags and extensions**: free labels, and an app's own data kept on the item ([Properties and metadata](/build/properties-and-metadata)).
* **Tables**: rows in typed columns, such as the messages of a conversation ([Tables](/build/tables)).
* **Edges**: typed links to other items, such as a photo attached to a note ([Edges](/build/edges)).
* **A file's bytes**: kept once as a **blob**, however many items name it ([Files](/build/files)).

## Changes [#changes]

Every item has a **version**, and a write names the version it read, so Marfa can tell when someone else changed the item in between. [Versions](/build/versions) explains what Marfa does then.

Changes are recorded as **events** in one log. An app follows the log to stay current, or registers a webhook so the instance posts changes to it. [Events and webhooks](/build/events) covers both.

## Who can reach it [#who-can-reach-it]

Nothing reads or writes an instance without a **credential**, and a credential reaches only what it was given: these types, read or edit, and these powers. A script or a connector uses a **key**. An app or an agent signs in with OAuth, so the owner sees what it asks for and approves it. [Access](/build/access) explains both.

## What reaches it [#what-reaches-it]

Every program that uses Marfa runs outside the server. What sits between it and the API differs:

* **The Swift SDK and the CLI** embed the **core**, a Rust engine that sends their requests and can keep a **working copy** of the items they need. A program with a working copy is a **device**: it reads offline and sends its writes when it can reach the instance, as [Devices](/build/devices) explains. A [synced folder](/use/sync-a-folder) is a device too: its working copy is a folder of ordinary files on your computer.
* **The TypeScript SDK** sends each request straight to the API, and keeps no copy. Web pages, scripts and connectors use it.
* **AI agents**, such as Claude or Codex, connect to the instance's **MCP server** at `/mcp`, or run the CLI, as [Connect your agent](/connect-your-agent) shows.
* **Connectors** are programs the owner runs that register with the instance and bring in records from another service, such as GitHub or a calendar, as [Connectors](/build/connectors) explains.



Apps made by WithMarfa reach the instance the same way, through the same API and the same credentials as anything you build.
