LuvLink

Your Luvus agents, within reach.
A private, mobile-first remote for Luvus, secured by Tailscale.

LuvLink gives you a focused view of the Luvus session running on your computer. From a phone on the same tailnet, you can inspect workspaces, follow agent output, send prompts, and bring a pane into focus on the desktop. No cloud relay, account, analytics, or third-party Python packages.

LuvLink is an independent community module for Luvus. It is not an official Luvus product.

_{Mobile dashboard shown with synthetic workspaces and agents.}

What you can do

• See every open Luvus workspace, tab, pane, agent type, and status.
• Keep workspaces with active work first and sort working panes first inside them.
• Optionally lift every working agent into a dismissible Working now shelf above the workspaces.
• Make active work obvious with a rotating segmented outline around each working agent.
• Collapse workspaces, hide the intro banner, and preserve those choices on the device.
• Use Luvus’s Quattro Rally palette by default, or choose LuvLink, Midnight, or Ember from mobile settings.
• Use native mobile page scrolling and pull-to-refresh on the dashboard.
• Follow terminal output without reflowing long status lines; optionally wrap lines, resize text, or jump back to the latest output.
• Prompt or steer an active coding agent from your phone.
• Receive browser notifications for blocked and completed agents while LuvLink is open.
• Choose whether Enter sends, expose Esc and Ctrl+C controls, and keep multiline input predictable.
• Close an agent pane from the focused view with confirmation enabled by default.
• Focus a selected pane in the desktop Luvus interface.
• Install the web interface as a PWA.
• Rotate mobile access immediately from Luvus.
• Use a stable private HTTPS address through Tailscale Serve.

Requirements

• Luvus 0.13.0 or newer
• Python 3.10 or newer
• Tailscale on the Luvus computer and mobile device
• Linux or macOS

Install

Install directly through Luvus:

luvus module install DavidCarliez/luvlink

For local development, clone and link the checkout instead:

git clone https://github.com/DavidCarliez/luvlink.git
luvus module link "$(pwd)/luvlink"

LuvLink starts automatically with the Luvus session. Start it manually when needed:

luvus module run community.luvlink start

Open LuvLink on your phone

Recommended: stable private HTTPS

Enable the Tailscale Serve route once:

luvus module run community.luvlink enable-https

LuvLink receives a stable address based on the computer's tailnet DNS name:

https://device-name.tailnet-name.ts.net:8443/

This does not enable Tailscale Funnel. The URL remains private to devices and users allowed by your tailnet policy. LuvLink uses port 8443 so it does not replace an existing Tailscale Serve route on 443.

If Tailscale reports a permission error, authorize your local user once and retry:

sudo tailscale set --operator="$USER"
luvus module run community.luvlink enable-https

Get the signed access link

Open the LuvLink Access overlay inside Luvus:

luvus module run community.luvlink show-url

Open that link on your phone. Its token is carried in the URL fragment, which the browser does not send in the HTTP request, and is then stored on that device.

Direct tailnet access

Without Tailscale Serve, LuvLink binds directly to the computer's Tailscale IPv4 address:

http://100.x.y.z:7788/

Disable the HTTPS route and restore direct mode with:

luvus module run community.luvlink disable-https

Actions

Action	Purpose
Start LuvLink remote	Start the local mobile backend.
Stop LuvLink remote	Stop all mobile access immediately.
Show LuvLink access details	Open the signed link in a Luvus overlay.
Rotate LuvLink access token	Invalidate every previously signed link and mobile session.
Enable Tailscale HTTPS URL	Add the private HTTPS route and bind the backend to loopback.
Disable Tailscale HTTPS URL	Remove only LuvLink's HTTPS route and restore direct mode.

Settings

Settings are available under Settings → Modules → LuvLink.

Setting	Default	Purpose
Start with Luvus	true	Start LuvLink with the Luvus session.
Bind address	auto	Detect the Tailscale IPv4 address; HTTPS mode sets loopback.
Port	7788	Local backend port.
Tailscale Serve HTTPS port	8443	Stable HTTPS listener on the tailnet DNS name.
Access token	generated	Secret bearer token used by mobile clients.

Security model

LuvLink is intentionally local-first:

• Direct mode listens on the detected Tailscale interface, not every network interface.
• HTTPS mode listens only on 127.0.0.1; Tailscale Serve is the sole network entry point.
• Every API request requires a bearer token checked with constant-time comparison.
• The access token is stored in Luvus as a secret setting and in the module state directory with mode 0600.
• Token rotation takes effect without restarting the server.
• The server sets a restrictive Content Security Policy and does not allow cross-origin access.
• No Funnel, hosted relay, external account, telemetry, or runtime dependency is used.

Anyone with the complete signed link can control connected agents. Treat it as a password. Rotate the token immediately if the link is exposed.

How it works

Phone browser
    │ private HTTPS over the tailnet
    ▼
Tailscale Serve :8443
    │ loopback HTTP
    ▼
LuvLink server :7788
    │ Luvus CLI / UHP
    ▼
Active Luvus session and agent panes

The Python server is a small authenticated adapter around the same Luvus CLI and Universal Harness Protocol used by local integrations. The mobile interface polls bounded session state and recent pane output; commands are passed as argument arrays rather than shell strings.

Troubleshooting

Inspect module command output:

luvus module log community.luvlink --limit 10

Check Tailscale Serve routes:

tailscale serve status

Restart only LuvLink:

luvus module run community.luvlink stop
luvus module run community.luvlink start

If a saved mobile token no longer works, run Show LuvLink access details again. Rotation deliberately invalidates the old token.

Development

There is no build step and no third-party runtime dependency.

python3 -m py_compile luvlink.py server.py
luvus module unlink community.luvlink
luvus module link "$(pwd)"
luvus module run community.luvlink start

The module manifest is luvus-module.toml; the backend is luvlink.py plus server.py; the PWA is under web/.

License

MIT