ResearchOS/Wiki

iCloud Drive

iCloud Drive Optimize Storage offloads unused files. Mark the ResearchOS folder Keep Downloaded so it stays local.

Enable iCloud Drive

On macOS, open System Settings → Apple ID → iCloud → iCloud Drive. Make sure it's turned on, and that the Desktop & Documents Folders sub-option is enabled if you plan to put the lab folder under ~/Documents.

Share the lab folder

  1. One member creates an empty folder inside their iCloud Drive (e.g., LabName-ResearchOS).
  2. Right-click the folder in Finder → Share → Collaborate. Set permissions to Only invited people and Can make changes.
  3. Send the share link to each lab member. They accept it on their Mac, and the folder appears in their iCloud Drive.

Keep Downloaded (every member, every Mac)

  1. In Finder, navigate to the shared lab folder under iCloud Drive.
  2. Right-click the folder and choose Keep Downloaded (it's near the bottom of the context menu). Every file inside downloads and the small cloud-with-arrow icon disappears.
  3. Wait for the Finder sidebar's iCloud status to read "Up to date".
  4. Open ResearchOS, click Link Folder, and pick that shared folder.

Common pitfalls

  • Optimize Mac Storage (System Settings → Apple ID → iCloud) will re-offload files macOS decides you haven't used recently. Keep Downloaded overrides this per folder, so make sure it's set on the lab folder, not just on individual files.
  • Permissions on shared collaborations are tracked by Apple ID. If someone's share is revoked, ResearchOS will see empty or unreadable files. Reaccept the share via the email link.
  • Hidden .icloud placeholder files appear if the file is online-only. If you see .taskname.json.icloud instead of taskname.json, the file isn't local. Run Keep Downloaded again.

Apple documentation