Phone (experimental)
Experimental in 0.1.0. Phone access works, but the phone page, its looks and the push setup may change between releases.
nsq can serve a small page for your phone: your agents with their status and pending question, each agent’s screen, a box to send the next prompt, buttons to answer a permission prompt and to interrupt. The phone is a window onto your computer — the agents keep running there.
Pair a phone
nsq phone on --lan # listen on your local network (port 8766)
nsq phone pair # show a QR code and the linkScan the QR code with the phone on the same Wi-Fi. nsq phone status shows whether phone access is
on and which phones are connected; nsq phone off switches it off.
Without --lan nsq listens on this computer only, which a phone cannot reach. Use --port <n> for
another port.
The pairing link carries the pairing token — treat it like a password, and don’t share it or a
screenshot of the QR code. nsq phone rotate replaces the token and signs every paired phone out.
What a phone can and cannot do
| A paired phone can | A paired phone cannot |
|---|---|
| see agents, their status and the pending question | start agents or run commands |
| read an agent’s screen | type arbitrary keys into a terminal |
| send a prompt (a busy agent gets it when its turn ends) | stop or remove agents, delete worktrees |
| answer a permission prompt: yes / always / no | change dangerous mode, the model or the CLI |
| interrupt the current turn | read or download files |
Notifications on the phone
While the page is open, the phone shows an alert (and vibrates, where the browser allows it) when an agent needs you. nsq 0.1.0 sends no push notifications to the phone: with the page closed, the phone stays quiet.
Away from home
Phone access is meant for your local network. The connection is plain HTTP inside your network, so anyone who can watch that network’s traffic could see the token: use it on networks you trust. To reach your computer from elsewhere, use a VPN you already have (for example Tailscale, or an SSH tunnel) rather than opening the port to the internet.