Project-local diagnostic sinks cause cloud-folder sync loops

[fafowayne]

Summary

.ok/local/ holds continuously-rewritten server logs and telemetry inside the project directory. When a project lives in a cloud-synced folder — iCloud "Desktop & Documents", Dropbox, Google Drive — this creates a permanent upload loop: the sync provider begins uploading the file, the file changes mid-upload, the upload restarts, and it never completes.

There is no documented way to relocate these files, so the only fix is moving the entire project out of the synced folder.

Reproduction

1. Create an OpenKnowledge project inside ~/Documents on macOS with iCloud "Desktop & Documents Folders" enabled.
2. Open the project so the server starts.
3. Observe Finder's iCloud upload indicator never clearing.

Measurement

The two files responsible:

• .ok/local/logs/server-current.jsonl — 6.2 MB
• .ok/local/telemetry/spans-current.jsonl — 6.8 MB

Measured growth on an idle-but-open project:

server-current.jsonl: 6539079 -> 6543523 bytes in 8s  (+4444 bytes)

Roughly 555 B/s sustained, ~48 MB/day. Docs state these rotate at ~50 MB and ~25 MB, so the file is large and never stops changing.

Finder reports a stale rollup that never clears (e.g. "7 items, 39.7 MB of 47.3 MB") because the upload restarts before it can finish. The files are invisible to the user because .ok is hidden, which makes this hard to diagnose — it presents as a mysterious permanent sync spinner.

Moving mv the project folder out of ~/Documents also fails with Operation timed out, because the file provider is holding it. ditto + verify + remove worked.

Why there is no workaround

• docs/reference/configuration lists no env var or config key for a log or data directory. Env vars documented include HOST, PORT, OK_MCP_AUTOSTART, OK_LOG_LEVEL — none relocate a directory.
• The schema hardcodes the path: "Write local diagnostic spans + logs under .ok/local/ for ok diagnose bundle to collect."
• .okignore only affects the document index, not what gets written.

Why this looks like an oversight rather than a design choice

.ok/.gitignore already documents this content as machine-local:

.ok/local/ holds per-machine runtime state. Anything inside is machine-local and never committed.

and warns that .ok/ root contains PII, hostnames, and absolute paths. That reasoning applies equally to file sync — but only version control was guarded against. git ignores it correctly; iCloud and Dropbox have no knowledge of .gitignore.

Notably, a user-level location already exists and is already used: ~/.ok/logs/ holds daily CLI diagnostics (cli.2026-09-21.log, etc.). Per-project server logs and telemetry appear to have simply landed on the other side of that split.

Secondary consequence: with Documents sync enabled, the .ok/ contents the project's own gitignore describes as PII are uploaded to the user's cloud account.

Suggested fixes (any one would resolve it)

1. Write per-project runtime logs/telemetry under ~/.ok/ (e.g. ~/.ok/projects/<hash>/logs/), matching the existing CLI log location.
2. Add a config key or env var to relocate .ok/local/.
3. At minimum, document the hazard in docs/reference/what-open-knowledge-writes, which currently describes .ok/local/ in detail without mentioning sync providers.

Environment

• macOS 27.0, Apple Silicon (M1 Pro)
• OpenKnowledge desktop app 0.77.1
• iCloud Drive with "Desktop & Documents Folders" enabled

Possibly related: #1126 (local telemetry affecting desktop cold start).