{"id":32692005,"url":"https://github.com/cgillinger/icloud-electron","last_synced_at":"2026-05-08T03:37:46.992Z","repository":{"id":321215805,"uuid":"1084959740","full_name":"cgillinger/icloud-electron","owner":"cgillinger","description":"A wrapper for icloud services to show on desktop or start menu. ","archived":false,"fork":false,"pushed_at":"2025-10-28T12:54:28.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T14:17:57.330Z","etag":null,"topics":["desktop-application","electron","icloud","icloud-drive","icloud-photos","linux","ubuntu"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cgillinger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T11:57:46.000Z","updated_at":"2025-10-28T12:54:31.000Z","dependencies_parsed_at":"2025-10-28T14:18:01.008Z","dependency_job_id":"589a547b-1bfd-45b8-b591-b6cc47388a31","html_url":"https://github.com/cgillinger/icloud-electron","commit_stats":null,"previous_names":["cgillinger/icloud-electron"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cgillinger/icloud-electron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgillinger%2Ficloud-electron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgillinger%2Ficloud-electron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgillinger%2Ficloud-electron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgillinger%2Ficloud-electron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cgillinger","download_url":"https://codeload.github.com/cgillinger/icloud-electron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cgillinger%2Ficloud-electron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282158360,"owners_count":26623994,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-01T02:00:06.759Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-application","electron","icloud","icloud-drive","icloud-photos","linux","ubuntu"],"created_at":"2025-11-01T15:01:51.196Z","updated_at":"2025-11-01T15:04:52.547Z","avatar_url":"https://github.com/cgillinger.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iCloud for Linux (Electron)\n\nAccess your iCloud services (Photos, Drive, Contacts) on Linux through dedicated application windows.\n\n![iCloud for Linux Screenshot](screenshot.png)\n\n## 🎯 What This Is\n\nThis is a **lightweight Electron wrapper** that gives you dedicated application windows for iCloud services on Linux. Think of it as having separate browser windows specifically for iCloud, launched from your application menu.\n\n### ✅ What It Does\n- Opens iCloud services in dedicated Electron windows\n- Creates desktop shortcuts for Photos, Drive, and Contacts\n- Maintains login sessions (you stay logged in)\n- Uses modern Chromium engine for full compatibility\n\n### ❌ What It Doesn't Do\n- Does NOT provide system integration (no file sync, no notifications)\n- Does NOT sync files to your local filesystem\n- Does NOT integrate with Linux file managers\n- It's essentially a dedicated browser for iCloud, not a native client\n\n## 🔧 Requirements\n\n- **Linux distribution** (tested on Ubuntu 24.04 LTS / Kubuntu 24.04 LTS)\n- **Node.js and npm** (version 18 or higher recommended)\n- **Apple ID account with password login** (passkey/biometric login is not supported)\n- Internet connection\n\n## 📦 Installation\n\n### Step 1: Install Node.js and npm\n\n**Ubuntu/Debian/Kubuntu:**\n```bash\nsudo apt update\nsudo apt install nodejs npm\n```\n\n**Fedora:**\n```bash\nsudo dnf install nodejs npm\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S nodejs npm\n```\n\nVerify installation:\n```bash\nnode --version\nnpm --version\n```\n\n### Step 2: Clone or Download This Repository\n\n```bash\ncd ~\ngit clone https://github.com/YOUR_USERNAME/icloud-electron.git\ncd icloud-electron\n```\n\nOr download as ZIP and extract to `~/icloud-electron/`\n\n### Step 3: Install Electron\n\n```bash\ncd ~/icloud-electron\nnpm install\n```\n\n### Step 4: Fix Electron Sandbox Permissions\n\nThis is **required** for Electron to run properly:\n\n```bash\nsudo chown root:root node_modules/electron/dist/chrome-sandbox\nsudo chmod 4755 node_modules/electron/dist/chrome-sandbox\n```\n\n### Step 5: Test the Application\n\n```bash\ncd ~/icloud-electron\nnpx electron . photos Photos\n```\n\nA window should open showing iCloud Photos.\n\n**⚠️ IMPORTANT - Login Instructions:**\n\nWhen the iCloud login screen appears:\n1. **DO NOT click \"Sign in with passkey\"** - it will hang and not work\n2. Click **\"Continue with password\"** instead\n3. Enter your Apple ID email and password\n4. Complete two-factor authentication when prompted (you'll get a code on your iPhone/iPad/Mac)\n5. Check **\"Keep me signed in\"** to stay logged in\n\nIf the window works and you can see the login screen, proceed to the next step!\n\n### Step 6: Install Launcher Script\n\n```bash\ncat \u003e ~/icloud-electron/icloud-electron.sh \u003c\u003c 'EOF'\n#!/bin/bash\ncd ~/icloud-electron\nnpx electron . \"$@\"\nEOF\n\nchmod +x ~/icloud-electron/icloud-electron.sh\nsudo ln -s ~/icloud-electron/icloud-electron.sh /usr/local/bin/icloud-electron\n```\n\n### Step 6b: Install iCloud Icons (Optional)\n\nDownload Apple-style icons for better integration:\n\n```bash\ncd ~/icloud-electron\nchmod +x install-icons.sh\n./install-icons.sh\n```\n\nThis will download iCloud icons to `~/.local/share/icons/icloud/`. If it fails, the app will use system default icons.\n\n### Step 7: Create Desktop Shortcuts\n\n```bash\n# Check if custom icons were installed\nif [ -d \"$HOME/.local/share/icons/icloud\" ]; then\n    PHOTOS_ICON=\"$HOME/.local/share/icons/icloud/photos.svg\"\n    DRIVE_ICON=\"$HOME/.local/share/icons/icloud/drive.svg\"\n    CONTACTS_ICON=\"$HOME/.local/share/icons/icloud/contacts.svg\"\nelse\n    # Fallback to system icons\n    PHOTOS_ICON=\"emblem-photos\"\n    DRIVE_ICON=\"folder-cloud\"\n    CONTACTS_ICON=\"x-office-address-book\"\nfi\n\nmkdir -p ~/.local/share/applications\n\ncat \u003e ~/.local/share/applications/icloud-photos-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Photos\nComment=Access iCloud Photos\nExec=/usr/local/bin/icloud-electron photos Photos\nIcon=$PHOTOS_ICON\nTerminal=false\nCategories=Network;Graphics;Photography;\nEOF\n\ncat \u003e ~/.local/share/applications/icloud-drive-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Drive\nComment=Access iCloud Drive\nExec=/usr/local/bin/icloud-electron iclouddrive Drive\nIcon=$DRIVE_ICON\nTerminal=false\nCategories=Network;FileTransfer;\nEOF\n\ncat \u003e ~/.local/share/applications/icloud-contacts-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Contacts\nComment=Access iCloud Contacts\nExec=/usr/local/bin/icloud-electron contacts Contacts\nIcon=$CONTACTS_ICON\nTerminal=false\nCategories=Network;Office;ContactManagement;\nEOF\n\nupdate-desktop-database ~/.local/share/applications/\n```\n\n## 🚀 Usage\n\n### Launch from Application Menu\n\nAfter installation, you'll find these applications in your menu:\n- **iCloud Photos** - Access your photo library\n- **iCloud Drive** - Access your cloud storage\n- **iCloud Contacts** - Manage your contacts\n\n### Launch from Terminal\n\n```bash\n# Photos\nicloud-electron photos Photos\n\n# Drive\nicloud-electron iclouddrive Drive\n\n# Contacts\nicloud-electron contacts Contacts\n\n# Notes (if you want)\nicloud-electron notes Notes\n\n# Mail (if you want)\nicloud-electron mail Mail\n```\n\n## 🔐 Login Information\n\n### ⚠️ Important: Passkey Login Does Not Work\n\nWhen you first open an iCloud service, you'll see a login screen. **DO NOT use \"Sign in with passkey\"** - it will hang and not receive the verification popup on your other Apple devices.\n\n**Instead:**\n1. Click **\"Continue with password\"**\n2. Enter your Apple ID email\n3. Enter your Apple ID password\n4. Complete two-factor authentication (you'll get a code on your iPhone/iPad/Mac)\n5. Check **\"Keep me signed in\"** to stay logged in\n\nAfter logging in once, all iCloud services will share the same session.\n\n## 🐛 Troubleshooting\n\n### \"FATAL: The SUID sandbox helper binary was found, but is not configured correctly\"\n\nRun this command:\n```bash\nsudo chown root:root ~/icloud-electron/node_modules/electron/dist/chrome-sandbox\nsudo chmod 4755 ~/icloud-electron/node_modules/electron/dist/chrome-sandbox\n```\n\n### Login screen is cut off or button not visible\n\nThe window is resizable. Just drag the corner to make it larger, or maximize it.\n\n### \"Your browser is not supported\" error\n\nThis shouldn't happen with Electron. If it does:\n1. Make sure you're using Electron 30 or higher: `npx electron --version`\n2. Update Electron: `npm install electron@latest`\n3. Repeat Step 4 (sandbox permissions) after updating\n\n### Multiple Electron instances causing errors\n\nIf you get IndexedDB or quota database errors:\n```bash\nkillall electron\n```\n\nThen try launching again.\n\n### Can't find the application in the menu\n\nUpdate your desktop database:\n```bash\nupdate-desktop-database ~/.local/share/applications/\n```\n\nLog out and log back in, or restart your desktop environment.\n\n## 📝 Adding More iCloud Services\n\nYou can create shortcuts for any iCloud service using this pattern:\n\n```bash\nicloud-electron \u003cservice-name\u003e \u003cwindow-title\u003e\n```\n\n**Available services:**\n- `photos` - iCloud Photos\n- `iclouddrive` - iCloud Drive\n- `contacts` - Contacts\n- `notes` - Notes\n- `mail` - iCloud Mail\n- `calendar` - Calendar\n- `reminders` - Reminders\n- `pages` - Pages\n- `numbers` - Numbers\n- `keynote` - Keynote\n\n### Creating Desktop Shortcuts for Additional Services\n\nYou can create desktop shortcuts for any iCloud service. Here are ready-to-use commands for all major services:\n\n**Note:** Replace `Icon=` paths below with your installed icon paths if you ran `install-icons.sh`. Otherwise, the system default icons will be used.\n\n**Notes:**\n```bash\nNOTES_ICON=\"${HOME}/.local/share/icons/icloud/notes.svg\"\n[ ! -f \"$NOTES_ICON\" ] \u0026\u0026 NOTES_ICON=\"accessories-text-editor\"\n\ncat \u003e ~/.local/share/applications/icloud-notes-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Notes\nComment=Access iCloud Notes\nExec=/usr/local/bin/icloud-electron notes Notes\nIcon=$NOTES_ICON\nTerminal=false\nCategories=Network;Office;\nEOF\n```\n\n**Mail:**\n```bash\nMAIL_ICON=\"${HOME}/.local/share/icons/icloud/mail.svg\"\n[ ! -f \"$MAIL_ICON\" ] \u0026\u0026 MAIL_ICON=\"internet-mail\"\n\ncat \u003e ~/.local/share/applications/icloud-mail-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Mail\nComment=Access iCloud Mail\nExec=/usr/local/bin/icloud-electron mail Mail\nIcon=$MAIL_ICON\nTerminal=false\nCategories=Network;Email;\nEOF\n```\n\n**Calendar:**\n```bash\nCALENDAR_ICON=\"${HOME}/.local/share/icons/icloud/calendar.svg\"\n[ ! -f \"$CALENDAR_ICON\" ] \u0026\u0026 CALENDAR_ICON=\"office-calendar\"\n\ncat \u003e ~/.local/share/applications/icloud-calendar-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Calendar\nComment=Access iCloud Calendar\nExec=/usr/local/bin/icloud-electron calendar Calendar\nIcon=$CALENDAR_ICON\nTerminal=false\nCategories=Network;Office;Calendar;\nEOF\n```\n\n**Reminders:**\n```bash\nREMINDERS_ICON=\"${HOME}/.local/share/icons/icloud/reminders.svg\"\n[ ! -f \"$REMINDERS_ICON\" ] \u0026\u0026 REMINDERS_ICON=\"task-due\"\n\ncat \u003e ~/.local/share/applications/icloud-reminders-electron.desktop \u003c\u003c EOF\n[Desktop Entry]\nType=Application\nName=iCloud Reminders\nComment=Access iCloud Reminders\nExec=/usr/local/bin/icloud-electron reminders Reminders\nIcon=$REMINDERS_ICON\nTerminal=false\nCategories=Network;Office;ProjectManagement;\nEOF\n```\n\n**Pages:**\n```bash\ncat \u003e ~/.local/share/applications/icloud-pages-electron.desktop \u003c\u003c 'EOF'\n[Desktop Entry]\nType=Application\nName=iCloud Pages\nComment=Access iCloud Pages\nExec=/usr/local/bin/icloud-electron pages Pages\nIcon=x-office-document\nTerminal=false\nCategories=Network;Office;WordProcessor;\nEOF\n```\n\n**Numbers:**\n```bash\ncat \u003e ~/.local/share/applications/icloud-numbers-electron.desktop \u003c\u003c 'EOF'\n[Desktop Entry]\nType=Application\nName=iCloud Numbers\nComment=Access iCloud Numbers\nExec=/usr/local/bin/icloud-electron numbers Numbers\nIcon=x-office-spreadsheet\nTerminal=false\nCategories=Network;Office;Spreadsheet;\nEOF\n```\n\n**Keynote:**\n```bash\ncat \u003e ~/.local/share/applications/icloud-keynote-electron.desktop \u003c\u003c 'EOF'\n[Desktop Entry]\nType=Application\nName=iCloud Keynote\nComment=Access iCloud Keynote\nExec=/usr/local/bin/icloud-electron keynote Keynote\nIcon=x-office-presentation\nTerminal=false\nCategories=Network;Office;Presentation;\nEOF\n```\n\n**After creating any desktop file, update the database:**\n```bash\nupdate-desktop-database ~/.local/share/applications/\n```\n\n## 🗑️ Uninstallation\n\n```bash\n# Remove desktop shortcuts\nrm ~/.local/share/applications/icloud-*-electron.desktop\nupdate-desktop-database ~/.local/share/applications/\n\n# Remove global launcher\nsudo rm /usr/local/bin/icloud-electron\n\n# Remove application folder\nrm -rf ~/icloud-electron\n\n# Remove stored data (login sessions, cache)\nrm -rf ~/.config/icloud-electron\n```\n\n## 🔒 Privacy \u0026 Security\n\n- This application runs entirely on your local machine\n- No data is sent to third parties (only to Apple's iCloud servers)\n- Login sessions are stored locally in `~/.config/icloud-electron/`\n- The application uses the same Chromium engine as Google Chrome\n- Your Apple ID password is only sent to Apple's servers (via HTTPS)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nMIT License - see LICENSE file for details\n\n## ⚠️ Disclaimer\n\nThis is an unofficial tool and is not affiliated with, endorsed by, or connected to Apple Inc. iCloud is a trademark of Apple Inc.\n\n## 🙏 Credits\n\n- Built with [Electron](https://www.electronjs.org/)\n- Inspired by the need for iCloud access on Linux\n\n## 📚 Keywords\n\nicloud linux, icloud ubuntu, icloud electron, icloud photos linux, icloud drive linux, icloud contacts linux, apple icloud linux, icloud web linux, icloud client linux, icloud wrapper linux, access icloud on linux, icloud debian, icloud fedora, icloud arch linux, icloud kde, icloud gnome\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgillinger%2Ficloud-electron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcgillinger%2Ficloud-electron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcgillinger%2Ficloud-electron/lists"}