Skip to content

docs(overview): fewer boxes and a clearer lead on the Overview #555

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aicayzer merged 2 commits into from
Oct 21, 2026
Merged

docs(overview): fewer boxes and a clearer lead on the Overview #555

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e5f29c
docs(overview): fewer boxes and a clearer lead on the Overview, diagr…
aicayzer Oct 21, 2026
886a476
Merge branch 'main' into docs/overview-copy
aicayzer Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions content/docs/(overview)/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ Most apps keep their own copy of your data, in their own shape. Marfa keeps it i

Marfa is open source under the Apache License 2.0. The rules it follows are written down in [the contract](https://github.com/withmarfa/marfa/tree/main/conformance/spec) and checked by tests.

## How it fits together

One running Marfa is an **instance**. It belongs to one person, its **owner**, and runs on a computer they choose: their own Mac, a home server, or a host such as Railway. Everything else connects to it.

<MarfaAtAGlance />

Apps, scripts and AI agents read and write over Marfa's HTTP API, each with a credential that reaches only the data it was given. Connectors bring in records from other services. [How Marfa works](/how-marfa-works) explains each part.

## What you can do with Marfa

- **Keep your data when you change apps.** Stop using an app, and everything it saved stays in Marfa for the next one.
Expand All @@ -19,14 +27,6 @@ Marfa is open source under the Apache License 2.0. The rules it follows are writ

If you know Apple's platforms, Marfa is **like iCloud, but for structured data and open to any app**. It's also **like HealthKit, but for any kind of data**: each app asks for the types it needs and sees no items of any other type.

## How it fits together

One running Marfa is an **instance**. It belongs to one person, its **owner**, and runs on a computer they choose: their own Mac, a home server, or a host such as Railway. Everything else connects to it.

<MarfaAtAGlance />

Apps, scripts and AI agents read and write over Marfa's HTTP API, each with a credential that reaches only the data it was given. Connectors bring in records from other services. [How Marfa works](/how-marfa-works) explains each part.

## What Marfa isn't

- **Not for teams.** An instance belongs to one person. It holds that person's data, and other people don't collaborate in it.
Expand Down
42 changes: 17 additions & 25 deletions content/docs/(overview)/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,38 @@
---
title: Overview
description: Marfa is a shared data layer for your apps, and you run it yourself. Find the page you need, from your first instance to the API reference.
description: Marfa is a shared data layer for your apps, and you run it yourself.
---

Marfa keeps your data in one place you own, as typed items, so your apps, scripts and AI agents work from the same data through one API.
Your notes, tasks, bookmarks and files live in one instance, as typed items. Your apps, scripts and AI agents read and write them through one API, each reaching only what you allow, and apps built on the Swift SDK keep working offline. These docs cover running an instance and building on it.

<Callout type="warn">Marfa is early, so expect breaking changes until version 1.0.</Callout>

## Get started
## Start here

<Cards>
<Card title="Introduction" href="/introduction">What Marfa is, what you can do with it, and where it runs.</Card>
<Card title="Quickstart" href="/quickstart">Start an instance on your computer and write your first note.</Card>
<Card title="How Marfa works" href="/how-marfa-works">The parts of Marfa, and how they fit together.</Card>
<Card title="Glossary" href="/glossary">The words Marfa uses, each with one meaning.</Card>
</Cards>

[How Marfa works](/how-marfa-works) then explains the parts, and the [Glossary](/glossary) defines the words these docs use.

## Build on Marfa

<Cards>
<Card title="Build an app with Swift" href="/guides/swift-app">An iPhone and Mac app that works offline.</Card>
<Card title="Use Marfa with AI agents" href="/guides/ai-agents">Give an agent a key that reaches only what it needs.</Card>
<Card title="Build a connector" href="/guides/connector">Bring records from another service into Marfa.</Card>
<Card title="Define a type" href="/guides/define-a-type">Register a type of your own, with its fields.</Card>
</Cards>
Apps and agents share the same data, through the Swift and TypeScript SDKs, the CLI or plain HTTP.

- [Build an app with Swift](/guides/swift-app): an iPhone and Mac app that works offline.
- [Use Marfa with AI agents](/guides/ai-agents): give an agent a key that reaches only what it needs.
- [Build a connector](/guides/connector): bring records from another service into Marfa.
- [Define a type](/guides/define-a-type): register a type of your own, with its fields.

## Run Marfa

<Cards>
<Card title="Deploy" href="/guides/deploy">Run an instance on your Mac, a home server or Railway.</Card>
<Card title="Back up and restore" href="/guides/back-up-and-restore">Copy an instance's data and secrets, and bring them back.</Card>
<Card title="Upgrade" href="/guides/upgrade">Check that a new build can open your data, then move to it.</Card>
<Card title="Troubleshooting" href="/guides/troubleshooting">The cause and the fix for the problems people meet first.</Card>
</Cards>
An instance is one SQLite database file and a folder of files, on your Mac, a home server or Railway.

- [Deploy](/guides/deploy): choose where it runs and how your devices reach it.
- [Back up and restore](/guides/back-up-and-restore): keep a copy of the data and secrets, and bring them back.
- [Troubleshooting](/guides/troubleshooting): the cause and the fix for the problems people meet first.

## Reference

<Cards>
<Card title="Catalog" href="/catalog">The types, edges, events and permissions every instance ships.</Card>
<Card title="HTTP API" href="/api-reference">Every operation, with its requests and answers.</Card>
<Card title="CLI" href="/cli">Marfa's command-line tool, for you and your agents.</Card>
<Card title="TypeScript SDK" href="/typescript-sdk">Call your instance from TypeScript or JavaScript.</Card>
<Card title="Swift SDK" href="/swift-sdk">Give an iOS or macOS app a working copy that reads offline.</Card>
<Card title="Changelog" href="/changelog">What each release changed.</Card>
</Cards>
The [Catalog](/catalog) lists the types, edges, events and permissions every instance ships. The [HTTP API](/api-reference), the [CLI](/cli) and the [Swift](/swift-sdk) and [TypeScript](/typescript-sdk) SDKs are each documented in full, and the [Changelog](/changelog) says what each release changed.
Loading