Support SDK-managed on-device realtime messaging without a backend relay

[joshkarlin]

hi, i made photon over the last few months for myself to use whatsapp and signal on my lightphone 3 (plus sms cos why not). it works pretty well as a messaging hub (no calls) and i have had to deal with many kinks and issues along the way. this was all done pre-light sdk so i am now looking at how to migrate to the sdk and keep the current on-device functionality i.e. no separate whatsmeow/signal-cli server. i work as a software engineer (10+ years experience), and use both claude and codex as part of my daily work. photon is in a decent state architecturally and seems to fit with some of the requirements of the sdk and not others. biggest blocker seems to be the ability to run background services i.e. whatsmeow and signal java service. interested to know what you guys think about the approach and whether these sorts of access requirements cross a redline for the sdk design, and also whether this whole thing will be redundant at some point with a native light version of beeper/signal/whatsapp.

more detail below in the codex write-up. looking forward to how the sdk evolves and really love the phone itself.

---

Summary

Please provide a supported way for an SDK tool to maintain a long-lived, on-device network connection for realtime messaging.

The connection, protocol credentials, encryption keys, message decryption, and message database should remain on the Light Phone. Requiring a developer-operated backend to receive and forward messages through UnifiedPush is not acceptable for this use case.

I am developing Photon, an open-source messaging tool that currently runs Signal and WhatsApp linked-device clients directly on the Light Phone III.

Current SDK gap

Reviewed against light-sdk commit d2323e3.

The SDK currently provides:

• INTERNET, ACCESS_NETWORK_STATE, and WAKE_LOCK permissions.
• LightEntryPoint.onToolCreate() for initialization.
• LightWork for deferred WorkManager jobs.
• UnifiedPush delivery through onPushNotification().

None of these provides a supported lifetime for an on-device realtime client:

• onToolCreate() runs in the tool application process, but does not keep that process alive after the tool leaves the foreground.
• The SDK documentation explicitly describes LightWork as unsuitable for time-sensitive work. Periodic work also has a 15-minute minimum.
• The remote UnifiedPush path is explicitly registered for notifications "from the tool's backend." It therefore requires another machine to receive the original message and forward an event to LightOS.
• Tool code cannot declare or start its own Android service because custom manifests, android.app.*, Context, Intent, and startService() are restricted by the SDK plugin.

Starting a connection from onToolCreate() may work temporarily, but Android can terminate the background process. There is no documented restart, reconnection, or reboot behavior, so it cannot provide reliable messaging.

Required behavior

The exact API design should remain with the Light team, but a supported solution needs these properties:

1. The user explicitly enables and can revoke realtime operation for a tool.
2. An SDK-managed component keeps the registered protocol session alive while enabled and the device has network access.
3. The session continues when the tool UI is closed.
4. It is restarted after process death and, if the user left it enabled, after reboot.
5. Network transitions and temporary failures trigger bounded exponential backoff rather than tight reconnect loops.
6. The handler can use approved network libraries and access the tool private files or database through a sealed SDK context.
7. The tool can observe states such as starting, connected, backing off, disconnected, and disabled.
8. Disabling the capability stops the session and cancels pending reconnects.
9. LightOS owns any required foreground-service indication and can enforce battery, keepalive, and resource limits.

This could be implemented as an SDK-owned service with a registered handler, similar in spirit to LightWork. Tool code would not need access to Android Service, Context, receivers, or a custom manifest.

Because the SDK targets Android 14+, the implementation may need an appropriate foreground-service type and permissions. remoteMessaging may be relevant for linked-device messaging, but Light should select the type that matches its intended platform policy.

Message presentation

After the on-device session decrypts and stores a new message, it also needs a supported way to report that event to LightOS.

The existing UnifiedPush callback delivers data to the tool, but the SDK does not currently expose a user-visible notification, unread indicator, or conversation deep-link API. Ideally the realtime primitive would integrate with the notification model currently being considered for community tools.

This does not need to permit arbitrary full-screen alerts. A LightOS-owned, user-configurable message notification or unread toolbox indicator would be sufficient.

Acceptance scenario

1. Enable the realtime session and link an account.
2. Leave the tool and lock the phone for at least 30 minutes.
3. Change between Wi-Fi and cellular connectivity.
4. Send a message from another device.
5. The phone receives, decrypts, and stores it within seconds without any developer-operated relay.
6. LightOS presents the configured notification or unread indication.
7. Tapping it opens the relevant tool or conversation.
8. Reboot the phone and repeat without manually reopening the tool.
9. Disable realtime operation and verify that the connection does not restart.

Security and battery constraints

I am not requesting unrestricted background execution or general Android service access. Reasonable controls would include:

• Explicit per-tool user consent.
• Availability only to Light-signed or Light-approved tools.
• A limit on concurrent sessions.
• SDK-enforced reconnect backoff and keepalive policy.
• A persistent LightOS indication while a session is active.
• A system-level switch to inspect or revoke background access.

Is an SDK-managed on-device realtime session something Light intends to support, or is the current architecture intentionally limited to tools that can receive events from an external backend?

[dupontgu]

tl;dr - not coming short term, but not closing the door on stuff like this entirely

Sorry for being non-committal but here's where our thinking is with this kinda stuff:

• We loooove the idea of deploying tools with no additional cloud components. We know we're asking alot by requiring community tools to be free and open source, and we recognize that as it currently stands, costs for any custom backends for these tools would fall on the community. This is why we're going hard on the FileManager/local api.
• We know how badly everyone wants alt messaging. I think we're open to branching out beyond our normal restrictions if we can get big wins on this front.

however

• Our biggest fear with allowing tools that are built on reverse-engineering / likely break third-party TOS is that they will break with no notice. And the fact is, our users are going to flood our inbox when that happens.
• Legally, we're not sure what's safe for us as a software "distributor"? We have some research to do here before we go too wild.
• The whole reason for keeping the SDK capabilities so limited is that we can always a relatively good idea of how a tool built with it will behave without needing to analyze/test it too much (we don't have the resources for that currently), and allowing for arbitrary background services to run would undermine that. We know there are plenty of cases where they make perfect sense, but we're hesitant to just add support to the SDK. Kind of hoping that someday we'll have a set of "dangerous" APIs available to play with, and can work with devs individually to green-light specific use cases.
• As you mention, we'd need to build out some UX for users to see/manage background work. We are currently working on notification indicators, but that doesn't include the notion of "sticky" notifs. I don't see this climbing to the top of the backlog soon.

[joshkarlin]

thanks for the response!

absolutely understand those fears, especially around the potential flood of disappointed users when whatsapp decides to change their protocol overnight. v similar situation with the Punkt MP02 and their port of Signal as their own app, Pigeon - constantly playing catchup and is usually broken. puts a lot of pressure on a dev team and i'm sure you guys have enough stuff you'd rather be working on than that. Beeper, as I've seen suggested and considered, seems like a good way to have those integrations be externally managed, but I'm not aware of the details of whether that is possible commercially or otherwise. from the outside at least, seems like a partnership of some sort there would be ideal.

the TOS thing is interesting, and hard to know for sure where this lands. iirc it seemed to be technically breaking TOS but in the same way that using Beeper for whatsapp is technically breaking TOS, and that while there is a risk of account bans for that, it is v small. but of course, small is not none so that is much easier for me to risk as an individual than Light to encourage as a company. all a bit of a minefield so I do understand the careful approach on this stuff.

SDK being limited also makes complete sense, and overall i'm just really glad you guys have stepped in the SDK direction. difficult balance but giving people even very restricted capabilities tends to result in pretty cool and surprising outcomes. restricted/approved dev access to dangerous APIs would be cool, I'd be interested in guinea-pigging anything like that if you ever need external testers.

for Photon, I'll continue using it as whatsapp is essential this side of the pond, and signal is as well for me, so i will try to iron out the rest of the bugs and see which parts i can utilise the SDK for. if there are any considerations or requirements from your side that would make Photon more useful as a fully external test example for messaging then let me know. i'm not an android dev by trade so this has been a fun learning experience so far. will be looking at what other useful tools i can use the SDK to build as well