How to Use the Telegram Bot for Remote Re-authentication When the iCloud Cookie Expires

The docker-icloudpd container includes a two-way Telegram bot that lets you trigger a fresh iCloud authentication flow remotely by sending a specific command, eliminating the need to open a shell inside the container when your cookie expires.

The boredazfcuk/docker-icloudpd image ships with a built-in Telegram integration that handles remote re-authentication through a simple chat interface. When your iCloud session cookie expires—typically every 30 days or after password changes—Apple requires Multi-Factor Authentication (MFA) renewal. Instead of executing commands inside the running container, you can use the Telegram bot for remote re-authentication to trigger the entire flow from your phone.

How the Telegram Bot Handles Remote Re-authentication

The remote re-authentication system consists of several coordinated scripts that manage bot initialization, message polling, command parsing, and the actual cookie regeneration.

Bot Initialization and Verification

When the container starts, launcher.sh (lines 673-702) checks the telegram_bot_initialised variable. If this is set to false (the default), the script sends a "ping" to the Telegram Bot API to verify the bot has received at least one message from your chat. If this check fails, the container logs a warning instructing you to send /start to the bot in Telegram.

Command Polling and Detection

Once initialized, the container enters a polling loop controlled by sync-icloud.sh (lines 2390-2411). This loop repeatedly calls the Telegram getUpdates method, looking for new messages. When you send the remote re-authentication command, the script detects it in the remote-sync block (lines 2434-2445).

The bot recognizes messages that begin with your configured user name (default: boredazfcuk) followed by the word auth. For example: boredazfcuk auth.

MFA Flow and Expect Script

Upon detecting the remote auth command, sync-icloud.sh (line 2445) executes the bundled authenticate.exp expect script in the background. This script initiates an iCloud login that triggers a push notification to your iPhone. After you approve the notification on your device, the script captures the MFA code displayed on your screen.

The sendmessage.sh script (lines 16-26) then sends you a Telegram message listing available MFA options and requesting the 6-digit code.

Cookie Regeneration

When you reply with the valid 6-digit MFA code, the container executes reauth.sh (lines 25-37). This script performs the actual remote re-authentication by:

1. Removing stale cookie files from /config
2. Running icloudpd --auth-only to obtain a fresh MFA-enabled cookie
3. Cleaning up temporary logs from /tmp/icloudpd/reauth.log

After successful completion, the bot sends a confirmation message and the regular photo sync resumes automatically.

Configuring the Telegram Bot for Remote Re-authentication

To enable remote re-authentication, you must set several environment variables. These are written to /config/icloudpd.conf by init_config.sh during container startup.

Required variables:

• telegram_token – Your bot token from BotFather (format: 123456789:ABCdefGhIJKlmNoPQRstuVWXyz)
• telegram_chat_id – The numeric chat ID where the bot will listen (e.g., -1001122334455)
• telegram_polling – Set to true to enable the polling loop (default: true)
• telegram_user – The username prefix for commands (default: boredazfcuk)

Optional variables for self-hosted setups:

• telegram_http – Set to true if using HTTP instead of HTTPS
• telegram_server – Custom Telegram API server address

Docker Compose Example

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:master
    container_name: icloudpd
    environment:
      - apple_id=you@example.com
      - apple_pass=********
      - telegram_token=123456789:ABCdefGhIJKlmNoPQRstuVWXyz
      - telegram_chat_id=-1001122334455
      - telegram_polling=true
      - telegram_user=boredazfcuk
    volumes:
      - ./config:/config
      - ./photos:/home/user/iCloud
    restart: unless-stopped

Step-by-Step Remote Re-authentication Process

When your iCloud cookie expires, follow these steps to re-authenticate remotely:

1. Open Telegram and navigate to your bot chat.

2. Send the authentication command using your configured username prefix:

   boredazfcuk auth

3. Approve the push notification on your iPhone when it appears.

4. Check the MFA code displayed on your iPhone screen (usually a 6-digit number).

5. Reply to the bot with the 6-digit code:

   123456

6. Wait for confirmation – the bot will notify you when reauth.sh successfully generates the new cookie and the sync resumes.

If the bot does not respond to the initial command, ensure you have previously sent /start to the bot so that telegram_bot_initialised is set to true in the container configuration.

Summary

• The Telegram bot for remote re-authentication in boredazfcuk/docker-icloudpd eliminates the need to access the container shell when iCloud cookies expire.
• The system uses launcher.sh for bot initialization, sync-icloud.sh for command polling, authenticate.exp for handling the MFA push notification, and reauth.sh for generating fresh cookies.
• Configuration requires telegram_token, telegram_chat_id, and optionally telegram_user to set the command prefix.
• Users trigger re-authentication by sending [username] auth followed by the 6-digit MFA code displayed on their iPhone.

Frequently Asked Questions

What message format do I use to trigger remote re-authentication?

Send a message that starts with your configured telegram_user value (default: boredazfcuk) followed by the word auth. For example: boredazfcuk auth. The bot detects this pattern in sync-icloud.sh (lines 2434-2445) and initiates the authentication flow.

Why does the bot ask me to send /start before authenticating?

The container verifies that the bot has been initialized by checking the telegram_bot_initialised variable in launcher.sh (lines 673-702). Sending /start to the bot in Telegram creates a chat history that the container can verify via the Telegram API. Until this check passes, the container logs warnings and ignores remote auth commands to prevent unauthorized access.

Can I use the Telegram bot for remote re-authentication with multiple Apple IDs?

Each container instance supports one Apple ID, but you can run multiple container instances with different apple_id values and separate Telegram bot configurations. Each instance requires its own telegram_token and telegram_chat_id (or separate chat IDs with the same bot), and each will respond independently to remote re-authentication commands sent to their respective chats.

What happens if I enter the wrong MFA code via Telegram?

If you send an incorrect 6-digit code, the authenticate.exp expect script will fail to validate the MFA challenge, and reauth.sh will not generate a valid cookie. The container will log the authentication failure and send an error message via Telegram. You must restart the process by sending the auth command again to generate a new push notification and obtain a fresh MFA code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}