The desktop app is the same workspace in a native window, with the same sidebar, editor, tabs and AI chat as the web app, plus two things a browser cannot give you. It can open any folder on your disk, and it can keep your cloud workspace in a real folder that other tools, terminals and editors can see.

## What it adds over the browser

- **Real folders.** Open a directory on your machine and edit it directly. Nothing leaves the computer, and you do not need to be signed in.
- **Your cloud workspace as files.** Your Monofile files appear as an ordinary folder under your home directory, kept in sync both ways, so `git`, `grep` and your other editors work on them.
- **Offline.** Keep writing with no connection. Changes queue and push when you are back.
- **Native window behaviour.** OS menus, find in page, and window state restored on relaunch.

## Installing and updating

Download the installer for your platform from the [releases page](https://github.com/ilgaribaldi/monofile-releases/releases): a `.dmg` for macOS on Apple silicon or Intel, and an installer for Windows. The app checks for new versions itself and installs them on Windows; on macOS, pick up a new build from the same page for now.

> [!NOTE]
> The current builds are not yet code signed for distribution, so the OS warns you on first launch. On macOS, open **System Settings**, then **Privacy & Security**, and choose **Open Anyway**. On Windows, SmartScreen asks you to confirm an unrecognised app.

## Signing in

Press sign in, and the app opens a page in your normal browser. You sign in there with the account you already use, and the page hands the app a long-lived key over a `monofile://` link. The app stores the key in your operating system's keychain and does not ask again until you sign out.

Local folders work without any of this. Your cloud workspace, the community and developer views, and the AI assistant need you signed in, and the assistant needs a Pro or Team plan, exactly as on the web.

## The two kinds of workspace

The workspace switcher at the top of the sidebar holds both kinds at once, and each remembers its own open tabs, so switching back puts you where you were.

| | Local folder | Personal, Cloud |
|---|---|---|
| Where the files are | Any directory you choose | A synced folder under your home directory, `~/Monofile/Personal` |
| Sign-in needed | No | Yes |
| Sync | None, it is your disk | Both ways, continuously |
| Version history and backlinks | Not available, these live server-side | Available, as on the web |

Opening the cloud workspace the first time clones it into the folder and shows the progress. After that the app pushes what you edit, pulls what changed elsewhere, and checks for remote changes every few seconds. Saves in a cloud folder are debounced slightly longer than in a local one. Each save is a sync round, and each round lands as one [[Changesets|changeset]] you can revert as a unit.

## The sync indicator

The chip in the footer says what the sync service is doing. Click it to run a round immediately.

| State | Meaning |
|---|---|
| `cloning n/m` | First open, pulling your workspace into the folder |
| `syncing` | A round is in flight |
| `synced` | The folder and your workspace agree |
| `pending N` | N changes the server refused; they are retried on the next round |
| `offline · N pending` | No connection; N local changes are queued |
| `locked by CLI` | Another process is syncing this folder; the app opened it without syncing and keeps retrying |
| `error` | Something other than the network failed, for example a folder pointing at a different account |

## Conflicts

When a file changed in both places, the local version wins by default and the cloud version goes into that file's history, so you can compare the two. The chip shows a conflict count; click it for the list, open any entry as a tab, and clear the list when you have looked. Conflict copies left in the folder by other tools are listed there too.

## Working offline

Edits you make with no connection go to the folder and count as pending. The next successful check runs a round and pushes them. Closing the app keeps them; reopening the workspace pushes whatever changed while it was shut.

## It will not fight the CLI

The desktop app and the CLI use the same folder conventions and the same lock. A folder you cloned with `monofile clone / ~/Monofile/Personal` opens in the desktop app as your cloud workspace, and a folder the app created works with [[Local Folders|monofile sync]]. Only one of them syncs a folder at a time. Whichever arrives second says `locked by CLI`, opens the folder without syncing, and takes over when the lock clears.

## Not in the desktop app yet

Canvas boards open as raw JSON. Share links, embeds, the graph view, semantic search and the assistant's change review card are web-only for now.

## Next steps

:::cards
- [[Local Folders]] — Clone and sync: keep a real directory in step with your workspace.
- [[Installing the CLI]] — Install with npx or globally, then authenticate.
- [[The AI Assistant]] — What the built-in assistant is, what it can touch, and the two modes.
- [[Changesets]] — Runs grouped into one reviewable, revertable unit.
:::