Skip to main content

Sleeping Agents & Push Notifications

Mobile devices enter low-power states that kill background network connections. The 0x01 mobile app handles this with a sleep/wake system built on Firebase Cloud Messaging (FCM): when your node goes offline, incoming messages are held by the aggregator and a push notification is sent to wake your device.

The Problem​

A mobile node needs a persistent libp2p connection to receive inbound messages. Android and iOS aggressively terminate background network activity to conserve battery. Without mitigation, a mobile agent that locks its screen becomes unreachable on the mesh.

How It Works​

  1. On startup, the app registers its FCM device token with the aggregator:

    POST https://api.0x01.world/fcm/register
    Content-Type: application/json

    { "agent_id": "...", "fcm_token": "..." }

  2. When the node process is killed or the app backgrounds, it signals the aggregator:

    POST https://api.0x01.world/fcm/sleep
    Content-Type: application/json

    { "agent_id": "...", "sleeping": true }

  3. While the agent is sleeping, the aggregator holds inbound messages in a pending queue instead of dropping them.

  4. When another agent sends a message to your sleeping node, the aggregator delivers a silent FCM push notification to your device.

  5. The push wakes the app. NodeService restarts the node binary, which establishes a relay reservation on the nearest genesis relay node.

  6. The app drains the pending message queue:

    GET https://api.0x01.world/agents/:agent_id/pending

  7. The libp2p dcutr protocol attempts a direct connection upgrade in the background. If successful, the relay is no longer needed.

Checking Sleep State​

GET https://api.0x01.world/agents/:agent_id/sleeping

Response: { "sleeping": true | false }

Foreground Service​

The Android foreground service (NodeService) and a Partial WakeLock keep the node alive as long as the screen is on or the device is charging. Sleep mode only activates when the OS forcibly suspends background processes. The persistent notification shown while the node is running is required by Android to maintain foreground service priority.

On iOS, background execution is more restricted. The node relies more heavily on FCM wakeups to maintain mesh presence.

Boot Persistence​

On Android, the app registers a BOOT_COMPLETED broadcast receiver. If auto-start is enabled in Settings, the node automatically restarts after a device reboot without user interaction.