Skip to content

Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.

Calmer, shorter install and first-run docs

Yashwanth Kamireddi8a06c1d1235b
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 7f7cbed..7dc0c99 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -23,16 +23,16 @@ You need **Rust 1.85+** ([rustup](https://rustup.rs)), **Node.js 22** and the sy
```sh
# Debian / Ubuntu
-sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
- librsvg2-dev libsecret-1-dev libheif-dev libfuse3-dev pkg-config
+sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev libsecret-1-dev \
+ libheif-dev libfuse3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev pkg-config
# Arch
-sudo pacman -S --needed webkit2gtk-4.1 gtk3 libsecret libheif libayatana-appindicator \
- gstreamer gst-plugins-base-libs fuse3 rust nodejs npm pkgconf
+sudo pacman -S --needed webkit2gtk-4.1 gtk3 libsecret libheif gstreamer \
+ gst-plugins-base-libs fuse3 rust nodejs npm pkgconf
# Fedora
-sudo dnf install webkit2gtk4.1-devel gtk3-devel libayatana-appindicator-gtk3-devel \
- librsvg2-devel libsecret-devel libheif-devel fuse3-devel pkgconf-pkg-config
+sudo dnf install webkit2gtk4.1-devel gtk3-devel librsvg2-devel libsecret-devel \
+ libheif-devel fuse3-devel gstreamer1-devel gstreamer1-plugins-base-devel pkgconf-pkg-config
```
Then:
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 7da6b3d..4844caa 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -71,7 +71,7 @@ body:
label: Platform
options:
- Linux
- - Windows (beta)
+ - Windows
validations:
required: true
diff --git a/README.md b/README.md
index 84bd02a..c6c3b2e 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ Notes, Reminders, Calendar, Contacts, Drive and Photos as fast desktop apps that
[![Flathub](https://img.shields.io/flathub/v/io.github.yashwanthkamireddi.Skykeep?logo=flathub)](https://flathub.org/apps/io.github.yashwanthkamireddi.Skykeep)
-->
-[Install](#install) · [Features](#features) · [Privacy](#privacy) · [FAQ](#faq) · [Contributing](#contributing)
+[Install](#install) · [First run](#first-run) · [Features](#features) · [Privacy](#privacy) · [FAQ](#faq) · [Contributing](#contributing)
<br>
@@ -98,104 +98,93 @@ Notes, Reminders, Calendar, Contacts, Drive and Photos as fast desktop apps that
## Install
-Packages arrive with the first release on the [Releases page](https://github.com/YashwanthKamireddi/Skykeep/releases), each with SHA-256 checksums.
+Download Skykeep from the [Releases page](https://github.com/YashwanthKamireddi/Skykeep/releases). Each release comes with SHA-256 checksums.
-| Platform | Package |
-|---|---|
-| **Debian, Ubuntu, Mint** | `.deb` |
-| **Fedora, openSUSE** | `.rpm` |
-| **Any Linux** | `.AppImage` |
-| **Arch, CachyOS, EndeavourOS, Manjaro** | AUR `skykeep-git` <sub>coming to the AUR</sub> |
-| **Any Linux, sandboxed** | Flatpak <sub>coming to Flathub</sub> |
-| **Windows 10 and 11** | `.exe` or `.msi` |
+### Windows 10 and 11
-<details>
-<summary><b>Debian and Ubuntu</b></summary>
+Run `Skykeep_<version>_x64-setup.exe`. It installs just for you, with no administrator password.
+
+If Windows shows **Windows protected your PC**, choose **More info**, then **Run anyway**.
+
+### Linux
+
+Run the line for your system from the folder you downloaded to.
+
+**Ubuntu, Debian, Linux Mint**
```sh
sudo apt install ./Skykeep_*_amd64.deb
```
-</details>
-<details>
-<summary><b>Fedora and openSUSE</b></summary>
+**Fedora**
```sh
-sudo dnf install ./Skykeep-*.x86_64.rpm # Fedora
-sudo zypper install ./Skykeep-*.x86_64.rpm # openSUSE
+sudo dnf install ./Skykeep-*.x86_64.rpm
```
-</details>
-<details>
-<summary><b>AppImage</b></summary>
+**Arch, CachyOS, EndeavourOS, Manjaro** <sub>coming to the AUR</sub>
```sh
-chmod +x Skykeep_*_amd64.AppImage
-./Skykeep_*_amd64.AppImage
+paru -S skykeep-git # or: yay -S skykeep-git
```
-Uses the WebKitGTK 4.1 and libsecret already on most desktops.
-</details>
+**Any other distribution**
+
+```sh
+chmod +x Skykeep_*_amd64.AppImage && ./Skykeep_*_amd64.AppImage
+```
<details>
-<summary><b>Arch and derivatives</b></summary>
+<summary><b>Other ways to install</b></summary>
+
+**Windows installer package.** The `.msi` on the Releases page installs the same app.
-Once it's on the AUR:
+**Flatpak** <sub>coming to Flathub</sub>. The manifest is in [`packaging/flatpak`](packaging/flatpak). In the Flatpak, iCloud Drive and Photos open inside the app.
```sh
-paru -S skykeep-git # or: yay -S skykeep-git
+flatpak install flathub io.github.yashwanthkamireddi.Skykeep
```
-Today, build the same package from a checkout:
+**Arch, from a checkout.** Builds and installs Skykeep from the source you cloned:
```sh
git clone https://github.com/YashwanthKamireddi/Skykeep.git
cd Skykeep/packaging/arch && makepkg -si
```
-Add `fuse3` to see iCloud Drive and Photos as folders in your file manager.
-</details>
-
-<details>
-<summary><b>Flatpak</b></summary>
+**iCloud Drive and Photos as folders** in your file manager need `fuse3` (on Arch: `sudo pacman -S fuse3`).
-The manifest lives in [`packaging/flatpak`](packaging/flatpak). Once it's on Flathub:
-
-```sh
-flatpak install flathub io.github.yashwanthkamireddi.Skykeep
-```
-
-In the Flatpak, iCloud Drive and Photos open inside the app.
+**From source:** see [Contributing](#contributing).
</details>
-<details>
-<summary><b>Windows</b></summary>
+## First run
-Run `Skykeep_*_x64-setup.exe` (installs for you alone, no admin needed) or the `.msi`. Skykeep opens `.ics` and `.vcf` files, and its alerts come with **Complete** and **Snooze**.
-</details>
+1. **Sign in** with your Apple Account and password.
+2. **Approve** the sign-in on your iPhone or another Apple device, then type the six-digit code it shows. No prompt? Choose **Didn't get a code?** to get one by text message.
+3. **You're set.** Each app fills in as your library arrives. After that, everything opens instantly.
+
+Your password stays on this computer: Skykeep proves it to Apple without sending it, and keeps your sign-in in your system keyring. [How Skykeep handles your data](SECURITY.md).
-**First run:** open Skykeep, sign in with your Apple Account, and enter the code from your iPhone. Each app fills as your library arrives, then opens instantly from then on.
+On Linux, your desktop may ask you to unlock its keyring the first time. That's where Skykeep keeps your sign-in.
## Privacy
-- **Local-first.** Your library lives on your computer, so every app opens instantly and works offline. Changes you make offline are sent when you're back online.
-- **Credentials stay in your system keychain.** You sign in through Apple's own two-factor flow, and your password and account tokens are kept in the keychain, never in a file: Secret Service on Linux, Credential Manager on Windows.
-- **Talks only to Apple.** Skykeep's network layer reaches Apple's iCloud hosts, plus any calendars you subscribe to. No Skykeep account, no Skykeep server, no telemetry.
+- **Local-first.** Your library lives on your computer, so every app opens instantly, even offline.
+- **Your sign-in stays in your system keyring:** Secret Service (GNOME Keyring or KWallet) on Linux, Credential Manager on Windows. Two-factor sign-in is Apple's own.
+- **Talks only to Apple,** plus any calendars you subscribe to. No Skykeep account, no Skykeep server, no telemetry.
- **Independent.** Skykeep is an open-source project, not affiliated with or endorsed by Apple.
The details, with the code behind each one, are in [SECURITY.md](SECURITY.md).
-## Performance
-
-Measured on release builds. Numbers land with the first release.
-
+<!-- Performance: add this table once release builds are measured.
| | Linux | Windows |
|---|---|---|
-| Launch to a usable window | *to be measured* | *to be measured* |
-| Open a note from the list | *to be measured* | *to be measured* |
-| A change on iPhone shown here | *to be measured* | *to be measured* |
-| Memory with all six apps open | *to be measured* | *to be measured* |
-| Download size | *to be measured* | *to be measured* |
+| Launch to a usable window | | |
+| Open a note from the list | | |
+| A change on iPhone shown here | | |
+| Memory with all six apps open | | |
+| Download size | | |
+-->
## FAQ
@@ -205,6 +194,18 @@ Measured on release builds. Numbers land with the first release.
No. It's an independent, open-source app that works with iCloud. Apple, iCloud and iPhone are trademarks of Apple Inc.
</details>
+<details>
+<summary><b>Why does it need my Apple Account password?</b></summary>
+
+Notes, Reminders, Drive and Photos open only to a full sign-in with two-factor, the same one icloud.com uses. An app-specific password reaches only mail, contacts and calendars. Skykeep never sends your password, not even to Apple: it proves it with Apple's own SRP sign-in.
+</details>
+
+<details>
+<summary><b>Which Apple Accounts work?</b></summary>
+
+Personal Apple Accounts. Managed Apple Accounts from a school or workplace aren't supported yet.
+</details>
+
<details>
<summary><b>Does it work offline?</b></summary>
@@ -214,7 +215,7 @@ Yes. Everything you've synced is on your disk. Notes, reminders, events and cont
<details>
<summary><b>How fast do changes from my iPhone appear?</b></summary>
-Notes and Reminders arrive over Apple's push channel, usually in about a second. Calendar and Contacts are checked every few seconds while a window is open. Your own edits show the moment you make them.
+Notes and Reminders arrive over Apple's push channel, usually in about a second. Calendar and Contacts are checked every few seconds while you're using Skykeep. Your own edits show the moment you make them.
</details>
<details>
@@ -226,13 +227,13 @@ Yes, with **Access iCloud Data on the Web** turned on: on your iPhone, Settings
<details>
<summary><b>Can I take my data with me?</b></summary>
-Any time. Settings → Export Everything saves your notes as Markdown, events as iCalendar, contacts as vCard and CSV, and your files as they are.
+Any time. Settings → Export Everything saves your notes as Markdown, events as iCalendar, contacts as vCard, and your files as they are.
</details>
<details>
-<summary><b>Which desktops does it run on?</b></summary>
+<summary><b>Which systems does it run on?</b></summary>
-Any Linux desktop with WebKitGTK 4.1 and a keyring (GNOME Keyring or KWallet), on Wayland or X11, and Windows 10 and 11.
+Windows 10 and 11, and any Linux desktop with WebKitGTK 4.1 and a keyring (GNOME Keyring or KWallet), on Wayland or X11. The `.deb` is built on Ubuntu 24.04 and the `.rpm` is tested on Fedora 41.
</details>
## Contributing
diff --git a/SECURITY.md b/SECURITY.md
index 12b2882..a6eb88e 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,9 +1,9 @@
# Security
-Skykeep asks for your Apple Account password. That is a lot of trust to ask of an app made by
-one person, so this page says exactly what it does with it: what it talks to, what it keeps,
-and where. Every line here is true of the code in this repository; if one ever stops being
-true, that is a bug, and a serious one.
+Skykeep signs in to iCloud with your Apple Account. This page says exactly what it does with
+your password and your data: what it talks to, what it keeps, and where. Every line here is
+true of the code in this repository; if one ever stops being true, that is a bug, and a
+serious one.
## What Skykeep talks to
@@ -14,7 +14,7 @@ Apple, and to calendars you subscribe to — nothing else:
- `*.icloud.com` service addresses Apple gives the session (CloudKit, Contacts, Calendar,
iCloud Drive, Photos), `gateway.icloud.com` and `cvws.icloud-content.com` (downloads).
- `calendars.icloud.com` — Apple's public holiday calendars.
-- The host of each calendar you subscribe to by address (Calendar ▸ + ▸ New Subscription…),
+- The host of each calendar you subscribe to by address (Calendar ▸ + ▸ New Subscription),
and only once you have: a `webcal://` or `https://` address of a public calendar file.
This is enforced, not only promised: every network client Skykeep makes is built by
@@ -45,13 +45,14 @@ place opens in this computer's own map app (a `geo:` link), never a website.
## What Skykeep keeps, and where
-Everything is in your user's data folder (`~/.local/share/io.github.yashwanthkamireddi.Skykeep` on Linux),
-which is readable by you alone (mode 700):
+Everything is in your user's data folder: `~/.local/share/io.github.yashwanthkamireddi.Skykeep`
+on Linux, readable by you alone (mode 700), and `%APPDATA%\io.github.yashwanthkamireddi.Skykeep`
+on Windows.
-- **Your password, Apple Account and session tokens:** in the system keyring (GNOME
- Keyring, KWallet — the Secret Service), never in a file. The password is kept so a session
- that lapses can sign itself back in without asking; Apple asks for a code only when it
- stops trusting this computer.
+- **Your password, Apple Account and session tokens:** in the system keyring (the Secret
+ Service, such as GNOME Keyring or KWallet, on Linux; Credential Manager on Windows), never
+ in a file. The password is kept so a session that lapses can sign itself back in without
+ asking; Apple asks for a code only when it stops trusting this computer.
- **Session cookies:** `cookies.json`, readable by you alone (mode 600).
- **Your library:** `library.db` (SQLite) — notes, reminders, events, contacts, the Drive
and Photos listings — and caches of pictures and files you opened. These are not encrypted
diff --git a/docs/media/README.md b/docs/media/README.md
index 226027e..4ed2cd8 100644
--- a/docs/media/README.md
+++ b/docs/media/README.md
@@ -1,6 +1,6 @@
# Media for the README
-Every image the top-level `README.md` shows lives here. They are made from the real interface by `.uiverify/readme-shots.mjs`, on an invented demo library (`.uiverify/readme-fixture.mjs`) with drawn pictures (`.uiverify/readme-pictures.mjs`).
+Every image the top-level `README.md` shows lives here. They're taken from the real interface by `.uiverify/readme-shots.mjs`, using the demo library in `.uiverify/readme-fixture.mjs` and the pictures drawn by `.uiverify/readme-pictures.mjs`.
```sh
node .uiverify/readme-shots.mjs # every still, plus the hero animation
diff --git a/packaging/README.md b/packaging/README.md
index b7f289e..9f1780f 100644
--- a/packaging/README.md
+++ b/packaging/README.md
@@ -1,48 +1,51 @@
-# Getting Quince onto a machine
+# Packaging Skykeep
-Quince is only software if somebody other than its author can install it. This directory is
-what turns a build directory into that.
+Everything that turns a build into something people install.
-## Arch, and anything built on it — CachyOS, EndeavourOS, Manjaro
+| Path | What it is |
+|---|---|
+| `arch/` | A PKGBUILD that builds the checkout it sits in. |
+| `aur/` | The AUR package, `skykeep-git`: the same steps, built from GitHub. |
+| `flatpak/` | The Flatpak manifest for Flathub, with its own [README](flatpak/README.md). |
+| `apps/` | The six per-app launcher entries (Notes, Reminders, Calendar, Contacts, Drive, Photos). |
+| `*.desktop.in`, `*.metainfo.xml` | The main launcher entry and the AppStream data software centres show. |
+| `*.search-provider.ini`, `*.SearchProvider.service`, `*.krunner.desktop` | Results in GNOME Shell and KRunner search. |
+| `icons/` | The app, tray and notification icons. |
+| `linux-compat/` | `check.sh`: installs a package in a clean distribution container and checks it runs. |
+
+## Arch, CachyOS, EndeavourOS, Manjaro
```sh
cd packaging/arch
makepkg -si
```
-That builds from the checkout this file sits in and installs Quince the way any other program
-on the machine is installed: `quince` on the path, an entry in the application menu, an icon,
-and the licence where a package manager expects to find it.
-
-For the AUR the same PKGBUILD gains a `source=("git+…")` and a `pkgver()`; the build and
-package steps are already the ones that version would use.
+This installs Skykeep like any other program: `skykeep` on the path, launcher entries for the
+main app and each of the six apps, the icon, search providers and the licence.
-## Debian, Ubuntu, Fedora, or anything at all
+## Debian, Ubuntu, Fedora, AppImage, Windows
```sh
-npx tauri build --bundles deb,rpm,appimage
+npx tauri build
```
-leaves them under `target/release/bundle/`. The AppImage needs no package manager and runs
-anywhere with WebKitGTK.
+builds every bundle for the platform you're on (`.deb`, `.rpm` and `.AppImage` on Linux;
+`.msi` and the `-setup.exe` on Windows) under `target/release/bundle/`. Releases are built
+the same way by `.github/workflows/release.yml`, which installs and starts each Linux package
+before keeping it.
## Flatpak
-Not written yet, and deliberately not guessed at. It is the channel that matters most —
-Flathub is the only place a non-technical person installs anything with one click on any
-distribution — but it is also the one with real work in it: the GNOME runtime with Rust and
-Node SDK extensions, every crate and npm package vendored ahead of time by
-`flatpak-cargo-generator` and `flatpak-node-generator` so the build runs offline, `/app`
-instead of `/usr` throughout, and `--talk-name=org.freedesktop.secrets` in `finish-args` or
-the session cannot be kept inside the sandbox.
-
-Writing a manifest on a machine with no `flatpak-builder` to try it on would produce something
-that looks finished and has never been run. It is next, on a machine that can build it.
+See [`flatpak/README.md`](flatpak/README.md): how to build it, the permissions it asks for,
+and what's left before Flathub.
-## What Quince needs to run
+## What Skykeep needs to run
-`webkit2gtk-4.1` for the window, `libsecret` for the keyring. The app starts without the
-second and cannot stay signed in, which is most of the point of it.
+- `webkit2gtk-4.1` for the window and `libsecret` for the keyring. Without a keyring the app
+ starts but can't stay signed in.
+- `libheif` for HEIC photos.
+- GStreamer with the base, good and libav plugins for videos.
+- Optional: `fuse3`, for iCloud Drive and Photos as folders in the file manager.
## Opening files and quick capture
@@ -60,8 +63,8 @@ Calendar (`.ics`) and contact (`.vcf`) files open in Skykeep's import sheet
`Actions=` on the main entry and on the Reminders and Notes entries (right-click in a dock or
launcher).
-**Windows jump-list tasks are not set up.** A jump list's tasks are written by the running app
-through the shell's `ICustomDestinationList` COM interface; neither Tauri nor its NSIS/MSI
-templates have a way to declare them. Adding them means a Windows-only call at startup
-(`windows` crate, `Win32_UI_Shell`) registering two `IShellLink` tasks with the arguments
-above. Until then, the same commands work from a shortcut's Target field.
+**Windows jump-list tasks are not set up yet.** A jump list's tasks are written by the running
+app through the shell's `ICustomDestinationList` COM interface; neither Tauri nor its NSIS/MSI
+templates can declare them. Adding them means a Windows-only call at startup (`windows` crate,
+`Win32_UI_Shell`) registering two `IShellLink` tasks with the arguments above. Until then, the
+same commands work from a shortcut's Target field.
diff --git a/packaging/flatpak/io.github.yashwanthkamireddi.Skykeep.metainfo.xml b/packaging/flatpak/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
index 2aea315..3791631 100644
--- a/packaging/flatpak/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
+++ b/packaging/flatpak/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
@@ -19,21 +19,20 @@
<description>
<p>
- Skykeep keeps your iCloud calendar, reminders, notes, contacts and Drive on your own
- machine. Everything opens straight away and works without a connection, and what you
- change here reaches your other devices.
+ Skykeep brings your iCloud notes, reminders, calendar, contacts, Drive and photos to
+ your computer as fast desktop apps. Your library is kept on this machine, so everything
+ opens straight away, even offline, and what you change here reaches your iPhone and
+ your other devices.
</p>
<p>
- You sign in once with your Apple ID and stay signed in. Nothing is stored on anybody
- else's server: there is no Skykeep account and no Skykeep service, and your credentials
- never leave this computer.
+ Sign in once with your Apple Account. Your password stays on this computer, in your
+ system keyring. Skykeep talks only to Apple and to calendars you subscribe to: there is
+ no Skykeep account, no Skykeep server and no telemetry.
</p>
<p>
- Skykeep is an independent project. It is not made by, endorsed by, or affiliated with
- Apple, and it reaches iCloud through interfaces Apple has not published, which means
- they can change without warning. Services that Apple encrypts end to end — Health,
- Messages, Keychain and others — cannot be read by any client and are shown as
- unavailable rather than quietly left out.
+ Skykeep is an independent, open-source project. It is not made by, endorsed by, or
+ affiliated with Apple, and it reaches iCloud through interfaces Apple has not
+ published, so Apple may change them at any time.
</p>
</description>
diff --git a/packaging/io.github.yashwanthkamireddi.Skykeep.metainfo.xml b/packaging/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
index fc99171..3c35163 100644
--- a/packaging/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
+++ b/packaging/io.github.yashwanthkamireddi.Skykeep.metainfo.xml
@@ -17,21 +17,20 @@
<description>
<p>
- Skykeep keeps your iCloud calendar, reminders, notes, contacts and Drive on your own
- machine. Everything opens straight away and works without a connection, and what you
- change here reaches your other devices.
+ Skykeep brings your iCloud notes, reminders, calendar, contacts, Drive and photos to
+ your computer as fast desktop apps. Your library is kept on this machine, so everything
+ opens straight away, even offline, and what you change here reaches your iPhone and
+ your other devices.
</p>
<p>
- You sign in once with your Apple ID and stay signed in. Nothing is stored on anybody
- else's server: there is no Skykeep account and no Skykeep service, and your credentials
- never leave this computer.
+ Sign in once with your Apple Account. Your password stays on this computer, in your
+ system keyring. Skykeep talks only to Apple and to calendars you subscribe to: there is
+ no Skykeep account, no Skykeep server and no telemetry.
</p>
<p>
- Skykeep is an independent project. It is not made by, endorsed by, or affiliated with
- Apple, and it reaches iCloud through interfaces Apple has not published, which means
- they can change without warning. Services that Apple encrypts end to end — Health,
- Messages, Keychain and others — cannot be read by any client and are shown as
- unavailable rather than quietly left out.
+ Skykeep is an independent, open-source project. It is not made by, endorsed by, or
+ affiliated with Apple, and it reaches iCloud through interfaces Apple has not
+ published, so Apple may change them at any time.
</p>
</description>