Question regarding project status

[LarsFronius]

Hey @rhoopr 👋

Thanks for creating this - it's just what I was looking for 😁
I am curious if you already use this project for your own means? Would you say it is safe to use to mirror a photo library already? I see you have many open features you still want to get into 1.0, most of which don't sound critical to me for a "simple mirror".
Mostly just testing the waters here before I point this at a ~1.5TB library.

Thanks!

[rhoopr]

@LarsFronius thanks for checking it out! I do use it for my personal library -- I built it for myself, originally, "for fun", when icloudpd announced they're looking for a maintainer. The core sync functionality is locked in, the rest is mostly small feature additions. You can just tell it "go sync" and it'll fetch the whole thing no issues.

Roadmap is expanding to include some interesting stuff like immich integration and some other expansions beyond just "icloud downloader", but that core use case will always be available.

[LarsFronius]

Thanks, that's good to know!
I must be either running into #142 or the issue in icloudpd that icloud-photos-downloader/icloud_photos_downloader#1327 tried to fix.
I get an email from Apple that there was a website login but no 2FA prompt at the moment...will have to try another day or debug when I find some time.

[rhoopr]

@LarsFronius my working assumption is that it's part of the patch in icloudpd #1327 - I'm adding a small hotfix to ensure we manually Trigger a Push Notification during 2FA. Grab the new version when it's up (an hour or two) and give it another try!

[rhoopr]

v0.5.1's trigger_push_notification fires before checking if we can actually collect a 2FA code. In Docker (non-TTY), every restart cycle hits Apple's /bridge/step/0 + SRP auth, accelerating account lockout. Whoops! Hotfix on the way :)

[rhoopr]

This is fixed in #152. kei now stays running when 2FA is required and waits for you to submit the code. The workflow is:

1. Container starts, 2FA needed → kei logs a hint and fires the notification script
2. Submit the code: docker exec -it kei kei submit-code 123456
3. kei detects the update and retries auth automatically, sync begins

No changes to your docker-compose.yml needed, restart: unless-stopped is fine.

I've also updated the Docker wiki page with the new instructions.

v0.5.2 building now.

[LarsFronius]

Hmm, I don't want to take too much of your time really. I hope you just see this as a useful QA session :)
I just tested v0.5.2 and it doesn't look like the auth flow is quite there yet.

The behaviour looks like this:

Starting kei works well and it detects I require 2fa and waits.

$ docker compose up
Attaching to kei
kei  | 2026-04-03T17:32:06.673548Z  INFO kei: Starting kei concurrency=10
kei  | 2026-04-03T17:32:09.039782Z  INFO kei::auth: Two-factor authentication is required
kei  | 2026-04-03T17:32:09.040072Z  WARN kei: 2FA required 2FA required for XXX. Run: kei submit-code <CODE> --username lfronius@pm.me
kei  | 2026-04-03T17:32:09.040177Z  INFO kei: Waiting for 2FA code submission...

However, this does not trigger a 2fa code to be sent to me. So what should I now pass to the submit-code? I don't have the information yet.

The interesting bit is that if I use e.g. the last code I used on the website to run it:

$ docker compose exec -it kei kei submit-code XXXXXX
2026-04-03T17:30:02.955732Z  INFO kei::auth::session: Session file does not exist
2026-04-03T17:30:04.703798Z  INFO kei::auth: Two-factor authentication is required
2026-04-03T17:30:05.439206Z ERROR kei::auth::twofa: Code verification failed: wrong code
Error: Two-factor authentication failed: 2FA verification failed

This now triggers a new code to be sent to me.
If I use it, it's invalid as you can see in the logs, so that doesn't help :/

So kei during runtime needs to trigger sending of the 2fa, but then wait for submission.
Currently that appears to be mixed up / has a bit of a logic regression.

From a pure UX perspective I'd even argue it would be best if kei doesn't automatically trigger the 2FA code to be sent (imagine e.g. a restart at night or token expiry at a random time triggering the 2fa - that would be odd, right?).
It should do what it does now, which is just wait, but tell you to run something like kei 2fa-handshake and then that triggers sending the 2fa and then gives you an input field to pass it back into kei's state, turning that entire handshake into one controlled interaction.

[rhoopr]

I am not bothered by this at all, glad to have your input!

The new 2FA flow is a little different, so yeah, it's gotten clunky vs the old flow where Apple purely pushed the 2FA, the app didn't ask for it. Let me review the code path a little more and take your feedback into account.

[rhoopr]

OK, I see the bug in my logic - the two separate changes I made conflict in flow so it doesn't call for 2FA but tells you to submit-code 🤦 So then when you submit-code, it triggers the 2FA and now your code is stale. I will have to make sure I completely flush my own auth before doing 2FA testing from now on - I think that hid the deadlock.

In any case, I'm gonna clean up the bug and the UX and push a patch.

[rhoopr]

Hey! v0.6.0 is coming soon with a big focus on credential management, auth hardening, and general stability/robustness work.

Recommended setup: Start the container with only your username, then store the password in the encrypted credential store:

environment:
  - ICLOUD_USERNAME=you@example.com

# One-time setup after first start:
docker exec -it kei kei credential set --username you@example.com

This will save your password AES-256-GCM encrypted in the /config volume. Future starts read it automatically — no env var needed.

2FA will work the same way — when a code is needed the container pauses (no restart loops) and you submit it externally:

docker exec -it kei kei submit-code 123456

Tip: set up a --notification-script so you get a Slack/push/etc. alert when a 2FA code is required, instead of having to watch the logs.

If you'd rather not use the credential store, there will be two other env-free options:

• Docker secrets — --password-file /run/secrets/icloud_password
• External secret manager — --password-command "op read 'op://vault/icloud/password'" (1Password, Vault, pass, etc.)

I'll update the Docker and Credentials wiki pages with the full walkthrough once it ships.