Agent setup

flockfs setup                 # connect ~/flockfs to http://127.0.0.1:4317
flockfs setup ~/work/shared   # or any new, empty folder
flockfs setup --drive research  # another drive: ~/flockfs-research

flockfs setup is noninteractive and prints exactly one JSON object. It:

1. checks that a flockfs server answers at --url (FLOCKFS_URL, default http://127.0.0.1:4317) and that the token is accepted, and resolves the drive: --drive (FLOCKFS_DRIVE; id, slug or slug-id), else the agent token's drive, else the server's default drive. The default folder is ~/flockfs for the default drive and ~/flockfs-<slug> for any other (always siblings, never one inside another);
2. 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 DIR for that on purpose). Paths through symlinks are refused;
3. 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 to DIR/.flockfs/sync.log. Elsewhere, or with --no-autostart, a detached background flockfs sync process. A daemon already running for the folder is reused;
4. proves both directions with a unique probe file (server → folder, then a local save → server) and deletes the probe;
5. waits for the daemon to report saved and prints the result.

{"ok":true,"state":"saved","url":"http://127.0.0.1:4317",
 "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":"http://127.0.0.1:4317/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).

CredentialsCopy Anchor Link

The token comes from FLOCKFS_TOKEN or --token-file (default data/token, the key flockfs serve creates locally). For a shared server, ask its owner for a write-enabled agent token (flockfs_…, created in the web app or with POST /api/tokens); 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://.

From a source checkoutCopy Anchor Link

./scripts/setup.sh [DIR] [--check | --stop] [--open] [--no-autostart]

Builds the CLI, and if nothing answers at FLOCKFS_URL (loopback only) builds the web app, starts PostgreSQL via scripts/dev-db.sh (unless FLOCKFS_DATABASE_URL is set) and a detached flockfs serve (log and pid in .dev/). Then it runs flockfs setup. --stop also stops a server this script started, and nothing else. Environment: FLOCKFS_URL, FLOCKFS_TOKEN / FLOCKFS_TOKEN_FILE, FLOCKFS_DATABASE_URL, FLOCKFS_SETUP_STATE_DIR.

Agents without a filesystemCopy Anchor Link

Point them at MCP instead of a folder:

• local agents: flockfs mcp --url … --token-file … [--drive research] (stdio);
• remote/cloud agents: POST https://your-server/mcp with Authorization: Bearer <token> (Streamable HTTP, protocol 2025-06-18), or https://your-server/mcp/<drive> for a specific drive (bare /mcp is the token's drive, else the default). A read-only agent token gives read-only tools.