# Cloud sync with Dropbox

Back up your library projects and settings to your own Dropbox and open them on your other computers. What syncs, how conflicts and deletions are handled, and what each message means.

Cloud sync keeps a copy of your library projects and your settings in your own Dropbox. Connect the same Dropbox on another computer, download your projects there, and both computers keep them in step.

Cloud sync is experimental. Turn it on in **Settings → Experimentation → Cloud sync**, then open **Settings → Data Storage → Cloud sync**.

## Before you start

- You need a Dropbox account. A free Dropbox Basic account has 2 GB.
- Cloud sync works on macOS, Windows and Linux.
- Oleafly syncs only while it's open, including when it's minimized or its window is hidden. Nothing syncs while Oleafly is closed.
- Oleafly talks to Dropbox directly. There's no Oleafly server in between.

## Connect Dropbox

1. Open **Settings → Data Storage → Cloud sync** and select **Connect Dropbox**.
2. Your browser opens Dropbox's sign-in and approval page. Sign in there and approve Oleafly.
3. The browser says "You're connected", and Oleafly finishes connecting.

You sign in on Dropbox's own page, so Oleafly never sees your Dropbox password.

### If the browser can't hand back to Oleafly

After you approve, Dropbox sends your browser to a local address on your computer (127.0.0.1), and Oleafly picks up the sign-in from there. If that doesn't work, select **Trouble signing in? Paste a code instead**. Dropbox shows you a code. Copy it and paste it into Oleafly.

### What Oleafly can reach

- Oleafly can open only its own app folder in your Dropbox, `Apps/Oleafly`. It can't see any of your other Dropbox files.
- Sign-in uses OAuth with PKCE.
- On macOS and Windows, the sign-in token is kept in the operating system's keychain. On Linux, or when the keychain isn't available, it's kept in an encrypted file in Oleafly's data folder.
- The token never syncs. Each computer connects on its own.

### The Cloud sync card

Once you're connected, the card shows:

- The email address of the Dropbox account.
- A ring that shows how much of your Dropbox is used. It turns from green to yellow, orange and red as your Dropbox fills up, and it's red from 80%.
- **Sync on this computer**, the switch that turns syncing on or off here.
- **Sync automatically**, which sets how often Oleafly syncs.
- This computer's name. Click it to rename the computer.
- The **Projects** list.
- **Advanced**, with **Disconnect**.

## What syncs

### Projects

Every project in your library syncs, with its files, including the folder your main document compiles in. Oleafly quietly leaves these out of every project:

- Build output, such as `.aux` and `.log` files and the compiled main PDF
- The `.git` folder
- Oleafly's own working folders
- Temporary files from editors
- System files such as `.DS_Store`

A few other things don't sync either, and the project's row lists them as skipped, with the reason: symbolic links, `node_modules` folders, files larger than 16 GB, and files with [names that don't work on every computer](#renames-and-file-names).

Projects you opened from a folder elsewhere on your computer ([folders opened in place](/docs/library/#folders-opened-in-place)) don't sync. The Projects list tells you how many there are.

Git history and [checkpoints](/docs/checkpoints/) don't sync.

### Project details

Each project's `project.json` syncs too, so its name, main document, engine, cover color and other details follow it. A few details belong to one computer and stay there:

- Export paths
- Whether the project is hidden
- The TeX package spec
- The checkpoint capture policy
- Which project it was forked from

### Settings

Your app settings sync, including AI instructions, AI personas and your custom dictionary. Three settings are set separately on each computer: the **Cloud sync** and **Web browser** switches in Experimentation, and how often **Sync automatically** runs. That way the AI never gets the web browser on a computer just because you turned it on somewhere else.

AI chats, passwords, API keys and other secrets never sync.

## What's in your Dropbox

Everything goes in the `Apps/Oleafly` folder:

```text
Apps/Oleafly/
├── projects/
│   └── <project id>/
│       ├── files/          the project's files, under their own names
│       └── version.json    which version of each file belongs to the project
└── settings/
    └── settings.json       your synced settings
```

Project files keep their own names, so you can open them from Dropbox. Editing or moving files in `Apps/Oleafly` by hand isn't supported. Oleafly treats everything in that folder as untrusted and checks it.

## How a sync round works

Each round goes through the same steps:

1. Oleafly asks Dropbox which projects changed since the last round. When nothing changed, that takes one request.
2. It scans each project's files on this computer. It recognizes unchanged files quickly, without reading them again.
3. For each file, it compares three versions: the one on this computer, the one in Dropbox, and the last version both agreed on. That tells it which side changed.
4. It downloads changes from your other computers to a temporary place and checks each file against the fingerprint (hash) recorded for it. Only then does the file go into the project. If you changed that file on this computer after the scan, Oleafly leaves it alone until the next round.
5. It uploads changes from this computer, then compares Dropbox's own checksum with what it sent.
6. It saves the project's version record, with a check that no other computer saved one in between. If one did, the round runs again with the newer record, so neither computer's work is lost.
7. Last, it removes files you deleted on this computer from Dropbox.

## When Oleafly syncs

**Sync automatically** sets how often a round runs:

- Every minute (the default)
- Every 5 minutes
- Every 15 minutes
- Every hour
- Only when I choose Sync now

The first round runs about 20 seconds after Oleafly starts. While the Oleafly window is hidden, rounds run at most every 5 minutes. Changes to your settings sync about 3 seconds after you make them.

If a round fails, for example because you're offline, Oleafly waits longer before it tries again, up to 30 minutes. It goes back to the normal schedule once a round succeeds. It also syncs when your computer comes back online.

**Sync now** runs a round right away and shows one message with the result. Automatic rounds never show pop-ups. Their status appears in the Projects section: "Last synced" with a time, "Syncing your projects", or a line that describes a problem.

When something needs you, such as a full Dropbox, a paused project, a conflict copy or a settings choice, a small amber dot appears on the Settings button. Settings then opens on Cloud sync, so you see what's wrong first.

## Conflicts

If the same file changed on two computers between syncs, Oleafly keeps both versions. This computer's version stays under the original name. The other computer's version is saved next to it, named after the computer that wrote it and the date, such as `ch1 (Laptop 2026-10-14).tex`. A second conflict on the same day adds a number to the name. The project's row lists the conflict copies until you select **Dismiss**.

Open both files, keep what you want, and delete the copy you don't need.

`project.json` never gets a conflict copy. Its fields merge instead. Each computer's changes are kept, and if both computers changed the same field, this computer's value wins.

### Unsaved edits are safe

Sync never overwrites a file that's open in the editor with unsaved changes. Changes from your other computers wait. Once you save, the next round treats your edit like any other, so if both sides changed the file, you get a conflict copy.

An open file you haven't changed updates in the editor as soon as a change from another computer arrives. If a change lands while you're editing, the editor says the file changed on disk, and you choose **Reload** or **Keep mine**. New files and conflict copies show up in the file tree, and a file deleted on another computer closes here.

### Renames and file names

Changing only the upper and lower case of a file name counts as a rename, not a delete.

Oleafly skips these files and lists them under the project's row:

- Files whose names don't work on every computer, such as names with `:` or names like `CON.tex`
- Files whose names differ only by case from another name in the same folder. The file that already syncs keeps syncing.

The list also shows files Oleafly couldn't read here, or couldn't download or upload. A file that fails to download is tried again after an hour, or sooner if it changes.
## Deleting files

When you delete a file on one computer, it's deleted on your other computers too. There, the file goes to the system Trash or Recycle Bin, or to Oleafly's own trash folder if the system has none. You can get it back from there.

A record that's missing from Dropbox never deletes files on a computer. If someone deletes a project's folder in Dropbox by hand, Oleafly uploads the project again.

### Protection against deleting many files

If more than half of a project's files are deleted at once on one computer, and that's more than 20 files, Oleafly doesn't pass the deletion on. The same happens if every file in the project is deleted. Moving or renaming a folder doesn't count, because the files still exist. The project shows "Paused to protect your files" with two choices:

- **Put them back** restores the files from Dropbox.
- **Delete from Dropbox too** deletes them from Dropbox as well, after you confirm. Your other computers then lose them too.

## The Projects list

Each project in your library has a row that shows its size and when it last synced.

- Its switch syncs the project on this computer or pauses it here.
- A project that's only in Dropbox has a download button. **Download all** downloads every one of them, apart from projects that are in this computer's Recycle Bin. A downloaded project appears in your library.
- If the project is in this computer's Recycle Bin, downloading it restores it from the Recycle Bin instead of making a second copy. The next sync brings in the changes made elsewhere.
- A project downloaded from Dropbox opens in restricted mode until you trust it on that computer. You get the same trust prompt as for a [folder you open in place](/docs/library/#folders-opened-in-place).

### Remove a project from Dropbox

To free up space, choose **Remove from Dropbox** in the **…** menu on a project's row. That deletes the project's copy in Dropbox. The project stays on this computer and stops syncing here. Your other computers keep their copies and show "Removed from Dropbox on" followed by this computer's name.

Turn the project's switch back on to upload it again.

Projects that are only in Dropbox have **Remove from Dropbox** in their menu too. That deletes them from your Dropbox, so you can't download them on this computer afterwards. Computers that already have them keep their copies.

If Dropbox can't delete the folder right away, the project still shows as removed, and Oleafly finishes deleting it on a later sync.

## Storage and a full Dropbox

The ring on the Cloud sync card shows how much of your Dropbox is used, and turns red from 80%. A free Dropbox Basic account has 2 GB.

When your Dropbox is full, uploads stop but downloads keep working. A banner tells you, and each project that couldn't upload shows it. While it's full, Oleafly checks how much space is left before it uploads, so it never sends a file that can't fit. To make room, do one of these:

- Turn off sync for large projects.
- Remove projects from Dropbox.
- Free up space in Dropbox.

Sync carries on by itself once there's space.

## Offline and interrupted syncs

When you're offline, your edits stay on your computer and nothing is lost. Sync picks up again when the connection is back.

If a round stops halfway, for example because the network dropped or you closed Oleafly, the next round finishes the work. A long first backup saves its progress every 200 files or 256 MB, so it doesn't start over.

When Dropbox asks Oleafly to slow down, or has a temporary error, Oleafly tries again by itself.

If this computer runs low on disk space, downloads wait until you free some up. Uploads carry on.

## Settings sync

The first time a computer connects, Oleafly compares its settings with the ones in your Dropbox. If they're different, it asks once: "Which settings should Oleafly use?" Choose **Use Dropbox settings** or **Keep this computer's settings**. If you close the dialog, it doesn't come back by itself. The same two choices wait on the Cloud sync card, and nothing is overwritten until you pick one.

After that, settings merge by themselves:

- Changes to different settings on different computers are all kept.
- If the same setting changed on both, this computer's value wins.
- Lists, such as the words in your dictionary, are combined.

To load the settings from Dropbox yourself, open **Settings → General → Import** and choose **Import from cloud**. You get the same review step as when you import a settings file.

## Computers and accounts

### Name this computer

Each computer has a name. It starts as the computer's host name. Click the name on the Cloud sync card to change it. Your other computers show it on conflict copies and on "Removed from Dropbox" notes.

### Disconnect

Open **Advanced**, select **Disconnect** and confirm. Syncing stops on this computer and Oleafly's access to your Dropbox is removed. Your projects stay on this computer and in your Dropbox.

### Switch to another Dropbox account

Connecting a different Dropbox account starts fresh. Nothing is compared with the old account, and nothing is deleted because of it.

### When access ends

If Oleafly's access ends, for example because you removed Oleafly from Dropbox's connected apps, the card says "Dropbox access ended. Connect again to keep syncing." Select **Connect again**.

### A newer Oleafly on another computer

If another computer runs a newer version of Oleafly that saved a project in a newer format, older versions stop syncing that project and ask you to [update Oleafly](/docs/updates/).

## Safety checks

- Every file from Dropbox is checked against its recorded fingerprint before it replaces anything.
- Nothing from Dropbox is written into `.git`, outside the project folder, or through a symbolic link.
- Oleafly treats everything in `Apps/Oleafly` as untrusted and checks it.
- Oleafly doesn't add end-to-end encryption to your files in Dropbox. They're stored in your Dropbox like any other files.

## Troubleshooting

| Message or symptom | What to do |
| --- | --- |
| The browser doesn't hand back to Oleafly | Select **Trouble signing in? Paste a code instead** and paste the code Dropbox shows. |
| "Dropbox access ended. Connect again to keep syncing." | Select **Connect again** and approve Oleafly in your browser. |
| "Which settings should Oleafly use?" | Choose **Use Dropbox settings** or **Keep this computer's settings**. Close the dialog to decide later on the Cloud sync card. Nothing is overwritten. |
| "Paused to protect your files" | Many files were deleted at once. Choose **Put them back** to restore them, or **Delete from Dropbox too** if you meant to delete them. |
| A file such as `ch1 (Laptop 2026-10-14).tex` appears | It's a conflict copy from the computer it's named after. Compare the two files, keep what you want and delete the other. |
| A project's row says files were skipped | Open the list to see each file and why. Rename files whose names don't work on every computer or clash with another name. |
| An amber dot on the Settings button | Cloud sync needs your attention. Open Settings and read the Cloud sync card. |
| "Oleafly can't read the copy in your Dropbox, so this project isn't syncing." | Select **Replace with this computer's copy**. Anything that's only in the Dropbox copy is lost, so check your other computers first. |
| "Oleafly can't read the settings in your Dropbox." | Select **Use this computer's settings** to replace them. |
| "This computer is running out of disk space." | Free up disk space. Sync carries on by itself. |
| "This project has more than 100,000 files. That's too many to sync." | Move files the project doesn't need out of its folder. |
| "Removed from Dropbox on" a computer's name | That computer removed the project from Dropbox. Your copy here is safe. Turn on the project's switch to upload it again. |
| "Your Dropbox is full." | Turn off sync for large projects, remove projects from Dropbox, or free up space in Dropbox. Downloads keep working, and sync carries on once there's space. |
| "Couldn't reach Dropbox. Oleafly will try again." | Check your connection. Your edits stay on this computer, and Oleafly syncs once you're back online. |
| "This project was synced by a newer version of Oleafly. Update Oleafly to keep syncing it." | [Update Oleafly](/docs/updates/) on this computer. |
| A downloaded project opens in restricted mode | Trust it on this computer once you know what's in it. |
| Nothing syncs | Check that **Cloud sync** is on in Experimentation, **Sync on this computer** is on, and the project's switch is on. Oleafly syncs only while it's open. If **Sync automatically** is set to **Only when I choose Sync now**, select **Sync now**. |

Moving projects with Git instead? See [GitHub sync](/docs/github-sync/). For everything Oleafly keeps on your computer, see [Your files and data](/docs/where-your-data-lives/).