--- title: "How sync works" description: "What the sync engine does in the background, which files it skips, and how it protects your work when things go wrong." canonical_url: "https://trytree.house/docs/desktop/how-sync-works" last_updated: "2026-09-29" --- # How sync works What the sync engine does in the background, which files it skips, and how it protects your work when things go wrong. A synced folder is a two-way copy of one workspace. Change a file on your computer and it's uploaded; change it anywhere else, in the web app, over MCP or on a teammate's computer, and it's downloaded. The desktop app and the sync CLI share the same engine, so everything on this page applies to both. ## It runs in the background Sync is done by a small background process, separate from the app. It starts when you log in to your computer and keeps running when no window is open. Quitting the desktop app doesn't stop it: the menu item even says **Quit (sync continues)**. To actually stop syncing, pause the folder or sign out (see [manage synced folders](https://trytree.house/docs/desktop/manage-synced-folders)). While it runs, it: - notices changes in your folder as you save them; - checks the workspace for other people's changes about every 2 seconds; - does a full comparison of the folder and the workspace every 5 minutes, to catch anything missed, for example while your computer was asleep. ## When two edits collide If a file changes in two places before sync can pass one change to the other, neither is thrown away. One version keeps the file's name and the other is saved beside it as a [conflicted copy](https://trytree.house/docs/files/conflicted-copies), both in the workspace and in your folder. Compare them, keep what you want, and delete the copy. An edit always beats a delete. If you edit a file on your computer while someone else deletes it, your edit brings it back rather than being lost. ## Safety nets Sync is built so that a mistake on one computer can't wipe the workspace for everyone: - **If the folder goes missing**, because you moved it, renamed it or put it in the Bin, sync stops and reports an error instead of deleting everything from the workspace. Put the folder back and sync carries on by itself. To keep a folder somewhere else, move it with **Change Location…** from the menu bar icon, or `treehouse relocate` in the CLI. - **If a single pass would delete 25 or more files from your folder**, or the workspace suddenly looks empty, sync assumes something is wrong. It keeps your local files and uploads them again rather than deleting them. - **Every change is versioned.** Anything sync writes to the workspace can be [restored from history](https://trytree.house/docs/files/version-history). ## One folder, one workspace Each synced folder belongs to exactly one workspace, and each workspace syncs to one folder per computer. To work on several workspaces, sync each to its own folder. ## What doesn't sync Some files are never synced, in either direction. There's no way to add your own rules yet. - **Files:** `.DS_Store`, `4913`, anything ending in `.swp`, `.tmp` or `~`, and anything starting with `.#`. These are editor and system temporary files. - **Folders, anywhere in the tree:** `node_modules`, `.git`, `.hg`, `.svn`, `.venv`, `venv`, `__pycache__`, `.next`, `.nuxt`, `.output`, `.turbo`, `.cache`, `dist`, `build`, `target`, `vendor`, `.gradle` and `Pods`. These are dependency, version-control and build folders, which can hold tens of thousands of files. - **The `.treehouse` folder** at the top of your synced folder. The match is on the exact name, so a folder called `my-build-notes` still syncs. Other dotfiles, such as `.env.example` or `.prettierrc`, do sync. Files larger than your plan's [maximum file size](https://trytree.house/docs/account/plans-and-limits) are skipped, with a note in the sync log. > **Warning** > > The `.treehouse` folder holds this folder's settings and the key it uses to reach your workspace. Never share it, copy it into another folder, or commit it to a Git repository. ## Whose name is on the change Your synced folder connects with a key that belongs to you. Every change that arrives through it is shown in [Activity](https://trytree.house/docs/sharing/activity) as yours, whether you made it or an agent working in the folder did. To have an agent's changes labelled as the agent's, connect it over MCP with its own key. [How agents work with Treehouse](https://trytree.house/docs/agents/connect/how-agents-work) explains the difference. ## Private files and losing access Your synced folder includes your own [private files](https://trytree.house/docs/files/private-files), since you can see them. It never includes other people's. If a file or folder becomes private to someone else, sync removes your local copy of it, because you no longer have access. If you're removed from the workspace, the folder's key stops working and the folder stops syncing, showing **Sign in needed**. ## Related - [Conflicted copies](https://trytree.house/docs/files/conflicted-copies): When two edits to the same file collide, Treehouse keeps both. Here's what a conflicted copy is, how to spot one and how to resolve it. - [Keep files private](https://trytree.house/docs/files/private-files): Make a file or folder visible only to you and your own agents, even in a workspace you share with others. - [See what changed in a workspace](https://trytree.house/docs/sharing/activity): The activity feed shows every change and comment in a workspace, who made it, and whether it came from a person or an agent. - [How Treehouse works](https://trytree.house/docs/get-started/how-treehouse-works): Workspaces, versions, conflicted copies and attribution - the handful of ideas the rest of Treehouse is built on.