# Sync from login (/run/sync-from-login) Start the folder watch each time you sign in with marfa folders autostart, check that it runs, let it send error reports, and give it a key file on a machine nobody signs in to. `marfa folders autostart` starts [the watch](/run/keep-folders-running) when you sign in to the computer, in your own account, on macOS and Linux. Every folder then stays in step with no terminal left open. It needs no administrator. ## Turn it on [#turn-it-on] ```bash marfa folders autostart on ``` It starts the watch at once and says which file it wrote. The agent runs `marfa folders watch --exit-on-new-build`, by the path you ran the CLI by, so **the watch moves to each new build you install**. Running `on` again changes nothing unless the agent would differ, such as after the program moved. * **The agent:** on macOS a launchd agent, and on Linux a systemd user unit. It holds **no credential and no server**: each folder uses the keychain's credential for its server, so on Linux the keychain must be unlocked at login. With a [key file](#use-a-key-file-instead-of-the-keychain) it holds that file's path and nothing from it. * **The log:** `folder-watch.log` beside the folder registry, readable by you alone. At 1 MiB it moves to `folder-watch.log.1`. * **When the watch stopped:** a watch that `SIGTERM` or Ctrl-C stops exits 0, so the service manager doesn't start it again, and the last line of the log says so, such as `2026-10-29T12:00:00Z folders watch stopped by SIGTERM, sent by process 4821`. The time is UTC. The process is the one that sent the signal, and the line leaves it out where your system doesn't report one. If edits stop reaching the server, read the end of the log first. * **Output from before the log opens:** an error the watch makes before it opens its log, such as a log that can't be opened, goes to `folder-watch.launchd.log` beside the log on macOS, readable by you alone and moved to `folder-watch.launchd.log.1` at 1 MiB. On Linux the user journal keeps it: `journalctl --user -u marfa-folder-watch.service`. * **Restarts:** the service manager starts the watch again only after it fails, and no sooner than 30 seconds after it last started. * **The priority:** the watch gives way to what you are doing and keeps working when every core is busy. On macOS the agent sets `Nice` to 10 and `LowPriorityIO` to true, and sets no `ProcessType`, because launchd's `Background` class can starve the watch under full load. On Linux the unit sets `Nice=10`, `IOSchedulingClass=best-effort` and `IOSchedulingPriority=7`. On macOS the watch's threads also run at utility quality of service, however the watch starts. `marfa folders autostart on` refuses `--profile`, and the watch it starts doesn't read `MARFA_PROFILE`. ## Send error reports from the watch [#send-error-reports-from-the-watch] The agent doesn't inherit your shell, so **the watch carries the telemetry settings set in the shell that ran `on`**: `MARFA_POSTHOG_HOST` and `MARFA_POSTHOG_PROJECT_TOKEN` for error reports, and the `OTEL_*` settings for traces, as [What the CLI and apps send](/run/client-telemetry#what-the-cli-sends) lists. Set them, then turn it on: ```bash export MARFA_POSTHOG_HOST=https://eu.i.posthog.com export MARFA_POSTHOG_PROJECT_TOKEN= marfa folders autostart on ``` `on` names each setting it carried, or says it carried none, in which case the watch sends no reports. The values go to `folder-watch.env` beside the folder registry, readable by you alone, because a setting can hold a credential; the agent holds only the file's path. A setting already in the watch's environment wins over the file. **To change them, set them and run `on` again**: it rewrites the file and restarts the watch. Run with none set, or run `off`, and the file goes. ## After you upgrade the CLI [#after-you-upgrade-the-cli] When an upgrade, such as `brew upgrade`, puts a new build at the path the agent names, **the watch moves to it by itself.** The watch notices it, finishes the passes under way and ends with exit status 3, and the service manager starts the new build. Nothing it was sending is lost: what it hadn't reached stays in the folder, and the new build sends it. The log names both builds: ```text restarting for a new build: marfa 0.0.55 to 0.0.56; the watch ends once the passes under way finish, and the service manager starts /opt/homebrew/bin/marfa ``` A path that leads to no file, or to a file that isn't a build of the CLI, such as during an uninstall, is said once in the log, and the watch goes on. **An agent that an earlier build wrote doesn't move by itself.** `status` reports it as outdated, and `marfa folders status` says when a folder's watch runs another build than the command. Run `marfa folders autostart on` again with the same options, such as `--key-file`, to replace it. The same holds whenever `status` says the agent differs from what `on` writes now. ## Check it or turn it off [#check-it-or-turn-it-off] ```bash marfa folders autostart status marfa folders autostart off ``` `status` needs no server or credential. It reports: * Whether the agent is installed and running. * Whether the agent differs from the one `on` writes now, as one from an earlier build does, and that running `on` again with the same options replaces it. `--json` reports this as `outdated`. * Which program the agent runs, and whether that program is gone or isn't the one you ran. * Where the agent logs, and on macOS where launchd keeps the watch's output from before its log opens. * The key file the agent names, or none where it uses the keychain. * Which folders the watch isn't holding, and why, including each folder with no credential the watch can use. `off` stops the watch and removes the agent. If the service manager can't be asked, it still removes the agent's file, exits 3 and says what it couldn't stop. Another program can show the same state from [the folder sync status file](/folder-sync-status). ## Use a key file instead of the keychain [#use-a-key-file-instead-of-the-keychain] A login agent starts outside your shell and reads your own keychain. On a machine that no one signs in to, such as a server or an automated Mac, the keychain stays locked and would raise a prompt that nobody answers. **A key file replaces the keychain for the watch**, and the agent holds the file's path and never what is in it. Make a key with only the permissions the folders need, as [Manage keys](/run/manage-keys) shows, and write the file with two lines: ```bash MARFA_API_URL=https://marfa.example.com MARFA_API_KEY= ``` ```bash chmod 600 ~/.config/marfa/watch.env marfa folders autostart on --key-file ~/.config/marfa/watch.env ``` To run one watch by hand with the same file, use `marfa folders watch --key-file `. * **The file can live anywhere outside your folders.** It has to be a regular file with one name, owned by you, closed to the group and to others (mode 600), and with both lines and a server address. Otherwise the command exits 1 with `invalid` and says which fault, and `autostart on` writes nothing. A file inside a folder is refused, because the watch would send it to the server as one of the folder's files. * **The key is used for the folders on that server,** and the keychain is read for none. A folder on another server is reported as having no credential, and the key is never sent to it. * **The file is read again each time a folder is opened,** so a key you rotate in the file is the one used the next time the watch opens a folder. A file that has become unsafe holds that folder back, with the reason `invalid` in [the folder sync status file](/folder-sync-status), until it is fixed, and the other folders go on. * **`--key-file` replaces `--url`, `--key` and `--profile`:** giving any of them with it is a usage error, exit code 2. * **`autostart on` without the option** goes back to the keychain and replaces the agent. The rules behind this guide are in the [folders](https://github.com/withmarfa/marfa/blob/main/conformance/spec/folders.md) chapter of the contract.