Agent setup
flockfs login # once, in the browser (or: an agent token, see Credentials)
flockfs setup # connect ~/flockfs to your drive
flockfs setup ~/work/shared # or any new, empty folder
flockfs setup --drive research # another drive: ~/flockfs-researchflockfs setup is noninteractive and prints exactly one JSON object. It:
- checks that a flockfs server answers at
--url(FLOCKFS_URL) and that the token is accepted, and resolves the drive:--drive(FLOCKFS_DRIVE; id, slug orslug-id), else the agent token's drive, else the server's default drive. The default folder is~/flockfsfor the default drive and~/flockfs-<slug>for any other (always siblings, never one inside another); - checks the folder: it must be new/empty, or already synced with this exact server and
drive (a folder synced before the server had drives counts as its default drive's), and
it must not be inside another synced folder.
An existing, unrelated folder is refused: setup never uploads files implicitly
(use
flockfs sync DIRfor that on purpose). Paths through symlinks are refused; - starts always-on sync, pinned to the drive's permanent id (
--drive <id>, so renaming the drive changes nothing). On macOS this is a LaunchAgent (flockfs sync DIR --install): starts at login, restarts on crash, logs toDIR/.flockfs/sync.log. Elsewhere, or with--no-autostart, a detached backgroundflockfs syncprocess. A daemon already running for the folder is reused; - proves both directions with a unique probe file (server → folder, then a local save → server) and deletes the probe;
- waits for the daemon to report
savedand prints the result.
{"ok":true,"state":"saved","url":"https://app.flockfs.com",
"drive":{"id":"k3vzq2m7xa4b","slug":"main","name":"Main","default":true},"directory":"/Users/me/flockfs",
"reusedDaemon":false,"pid":4242,"autostart":{"kind":"launchd","plist":"…","loaded":true},
"checks":{"authenticated":true,"serverToFolder":true,"folderToServer":true},
"files":12,"conflicts":[],
"next":{"browser":"…","status":"flockfs status …","mcpHttp":"https://app.flockfs.com/mcp", …}}Errors are {"ok":false,"error":"…"} on stderr with exit code 1; the message says what to
do next (start the server, fix the token, pick an empty folder).
For a drive other than the default, next points at that drive: browser is
<url>/d/<slug>-<id>, mcpHttp is <url>/mcp/<slug> and mcpStdio includes
--drive <slug>. --check and --stop take --drive too (without a folder they find
~/flockfs-<slug>, or the ~/flockfs* folder whose checkpoint names that drive).
| Flag | Effect |
|---|---|
--check | Report health (daemon, connection, last sync, conflicts, server reachability) without changing anything. Exit 1 unless saved. |
--stop | Remove the LaunchAgent and stop the daemon (SIGINT, graceful). Files and the checkpoint stay. |
--open | Open the web app. For a local drive it uses a single-use, 60-second sign-in link, so nobody has to paste the key. |
--no-autostart | Use a detached process instead of a LaunchAgent (does not survive a reboot). |
--no-load | Write the LaunchAgent plist but do not call launchctl (tests, packaging); sync runs as a detached process for now. |
Credentials
After flockfs login nothing else is needed: setup uses that sign-in (its server and drive;
--drive picks among the drives you signed in to), and the background sync gets no token at
all. The LaunchAgent and the detached daemon are started with only --url and --drive <id>
and open the saved sign-in themselves (macOS Keychain, else ~/.flockfs), refreshing it as they
run, so sync survives restarts, reboots and the hourly token rotation. If the sign-in ends
(flockfs logout, revoked in Access, 30 days unused), sync stops working until flockfs login.
Without a sign-in (agents, servers), or to override it, the token comes from FLOCKFS_TOKEN or
--token-file:
export FLOCKFS_URL=https://app.flockfs.com FLOCKFS_TOKEN_FILE="$HOME/.flockfs/token"
flockfs setupUse a write-enabled agent token
(flockfs_…, created in the web app or with POST /api/tokens; ask a drive owner if you can't
create one); setup cannot create identities or grant itself permissions. The token is never put in process arguments, the plist, or the
output: the LaunchAgent reads it from DIR/.flockfs/token (mode 0600) and a detached daemon gets
it through its environment. Remote servers must use https://.
Agents without a filesystem
Point them at MCP instead of a folder:
- local agents:
flockfs mcp --url https://app.flockfs.com --token-file … [--drive research](stdio); - remote/cloud agents:
POST https://app.flockfs.com/mcpwithAuthorization: Bearer <token>(Streamable HTTP, protocol 2025-06-18), orhttps://app.flockfs.com/mcp/<drive>for a specific drive (bare/mcpis the token's drive, else the default). A read-only agent token gives read-only tools.