Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
Actions service (protocol v0)
Status: draft. Builds on protocol v0; breaking changes are allowed until v1. License: CC BY 4.0.
One-shot requests from one paired device to another: a phone locks its PC, puts it to sleep, or wakes it over the local network with Wake-on-LAN, and either device opens a web link on the other.
1. Capabilities
| ID | Offered by | Meaning |
|---|---|---|
pc.power |
PC | Locks or sleeps when a paired phone asks |
pc.wake |
PC | Shares its network adapter MAC and subnet broadcast addresses (pc.wake_info) so a paired phone can wake it |
link.open |
both | Opens web links a paired device sends |
task.notify |
both | Sends or shows watched PC task notifications (task.notify) |
Senders check the other device's capabilities first and don't send a request it doesn't offer.
2. Messages
All on the control stream. pc.power, link.open and task.notify are
requests answered with ok or error; pc.wake_info is a one-way event (no
id, no reply).
t = "pc.power" id = n b = { action: "lock" | "sleep" }
t = "link.open" id = n b = { url: text, title?: text }
t = "task.notify" id = n b = { id: text, title: text, active: bool, elapsed_ms: uint, exit_code?: int }
t = "ok" re = n
t = "pc.wake_info" b = { macs: [text, ...], broadcasts?: [text, ...] }
2.1 pc.power
Asks the PC to lock (show the sign-in screen) or to sleep. The PC answers
ok before it acts, and waits a moment before sleeping so the answer
leaves before its network goes down.
Errors: DENIED when the user turned PC actions off for the phone (the
pc_actions device toggle, on by default); UNSUPPORTED when the device
doesn't do this, or for an action it doesn't know.
Shutting down and restarting are deliberately not part of this version: they're too easy to set off by accident, and lose unsaved work.
2.2 link.open
Asks the receiver to open url, which MUST be an http, https or
geo: link of at most 4,096 bytes with no whitespace or control characters.
Receivers MUST check this themselves and answer BAD_MESSAGE to
anything else; no other kind of link is ever opened. An optional title
(e.g. the currently playing video's title) may accompany video handoff URLs so
both devices can record a friendly title alongside the timestamp and raw URL in
the timeline.
Map handoff uses either geo:<lat>,<lon>?q=... URIs or web map URLs (Google
Maps, Apple Maps, Bing Maps, OpenStreetMap). Video handoff preserves or
attaches the playback timestamp in the URL (?t=<seconds> / &t=<seconds>s on
YouTube, #t=<seconds>s on Vimeo, ?t=<seconds> on Twitch).
A PC opens http/https links in its default browser and converts geo:
URIs to an HTTPS map search URL. When the Android app is in the foreground, it
opens the link or map intent immediately (ACTION_VIEW, falling back to an
HTTPS map URL if no Maps app handles geo:); when in the background, it posts
a high-priority notification (Open, Open in Maps, or Continue watching)
the user taps to open it. INTERNAL means it couldn't be opened or shown.
2.3 pc.wake_info (Wake-on-LAN)
Sent by a PC to a paired phone on session startup and whenever the PC's network adapters or IPv4 addresses change:
macs: up to 8 6-byte hardware addresses of the PC's physical Ethernet and Wi-Fi adapters that are currently up, formatted as lowercase"aa:bb:cc:dd:ee:ff", with wired Ethernet listed first. All-zero (00:00:00:00:00:00) and broadcast (ff:ff:ff:ff:ff:ff) addresses are invalid.broadcasts(optional): up to 16 directed IPv4 subnet broadcast addresses (e.g."192.168.1.255") computed from those adapters' current IPv4 addresses and prefix lengths (ip | !maskfor prefix lengths1..=30).
When the user turns the pc_actions device toggle off for a phone, the PC
sends pc.wake_info with an empty macs list so the phone clears any
stored wake info for that PC.
The phone persists the latest pc.wake_info per PC in its store so it
survives restarts. To wake an offline PC, the phone sends the standard
102-byte Wake-on-LAN magic packet (6 × 0xFF followed by the 6-byte MAC
repeated 16 times) over UDP to ports 9 and 7, addressed to each stored
subnet broadcast address and 255.255.255.255, repeated a few times over
~2 seconds.
2.4 task.notify ("Ping me when it's done")
Sent by a PC (nectarlink notify-when <pid | -- command...>) to report a
watched process or command to a paired phone:
id: stable identifier for the task (1..=64ASCII graphic bytes).title: human-readable task name (1..=256characters, e.g."cargo test").active:truewhile the command is running;falsewhen it has finished or been cancelled.elapsed_ms: milliseconds the command has been running (whenactiveistrue, used by the phone to anchor its chronometer atnow - elapsed_msand re-sent on reconnect) or total duration (whenactiveisfalse).exit_code: omitted whileactiveistrue;Some(code)when the command finished (0for success, non-zero for failure);Nonewithactive = falsewhen watching was cancelled (dismisses the ongoing notification on the phone).
While active is true, the phone posts an ongoing, silent chronometer
notification (promoted to an Android 16+ Live Update with
setRequestPromotedOngoing(true) and setShortCriticalText). When active
becomes false with an exit_code, the phone replaces that notification in
place with a high-importance completion alert ("<title> finished" or
"<title> failed (exit <code>)", body "Took 4m 12s · <PC name>").
3. Rules
- Implementations MUST NOT log links, task titles, or hardware/IP
addresses in
pc.wake_infodebug output (v0 §11).