See the screen of your machines

A connected machine gives you terminals and agent sessions. Some work still needs the desktop itself: an installer with a window, a permission prompt, a browser that is signed in over there. This page puts the live desktop of that machine into a browser tab on your Mac or phone, and gives an agent a way to look at the same screen and press things on it.

It is built from parts that already exist (a VNC server, noVNC, Tailscale) and one installer of ours. It is a side road, and the page says where it ends: see what is not here before you put it on a machine.

What you need

Three things, and only the third is ours.

1. A machine with a desktop session and a VNC server on it. Which server depends on the system, see the table below. A server with no monitor and no graphical session has no screen to show: the page will open and stay empty. For that machine the road is the terminal, not the screen.
2. Tailscale on the machine and on every device you watch from, signed in to the same account. It is the only way in from outside.
3. Linux or WSL2 with systemd, where the installer runs. On Windows that is WSL on the same PC.

Only the first row has been run by us end to end, on one PC with Windows 11 and WSL2. The other rows are written from the documentation of those programs and wait for their first machine. If one of them does not match what you see, the page is wrong and we want to know.

Why not RDP on Windows: Windows Home cannot be an RDP host, and a road that fails on the first home PC is not a road.

On Windows, noVNC lives in WSL and reaches the VNC server through the WSL gateway. Allow incoming port 5900 in the Windows firewall from the WSL subnet only. Never forward port 5900 on your router.

Install with one command

On the Linux machine, or inside WSL, from a copy of the LogiShell repository:

sudo bash infra/remote-screen/install.sh --tailscale

The installer is four files in infra/remote-screen/. Today it runs from a checkout of the repository; it is not served from a public address yet.

What it does:

• installs git, python3 and venv through apt-get if they are missing;
• puts noVNC (pinned to a tag and a commit) and websockify into /opt/lsh-screen, in a python environment of their own, so system packages are not touched;
• starts a service, logishell-screen, that survives a reboot and listens on 127.0.0.1:6080 only;
• adds the command lsh-hands;
• with --tailscale, shows port 6080 to the devices of your own Tailscale network, and prints the address to open.

It does not install the VNC server (you did that in the step above), it does not touch the firewall, and it does not open a port to the internet.

Running it again is safe and keeps the earlier settings. Useful flags:

For a Mac, run the installer on a Linux machine in the same Tailscale network and name the Mac: --vnc-host <address of the Mac>.

When something is missing, the installer says so in words instead of failing halfway:

• No systemd. Nothing is installed. In WSL it is two lines in /etc/wsl.conf ([boot], systemd=true) and wsl --shutdown from Windows.
• --tailscale, but Tailscale is not installed or not signed in. The service is installed and works locally. Install Tailscale, run tailscale up, then run the installer with --tailscale again.
• The VNC server does not answer. The service is installed, and the last line tells you the page will stay empty until the server is on.

Open it from a Mac

Install Tailscale on the Mac and sign in with the same account. Then open:

http://<address of the machine in Tailscale>:6080/vnc.html?autoconnect=1&resize=scale

The installer prints this address at the end. It is also the output of tailscale ip -4 on the machine. The page asks for the VNC password, and then you see the desktop and can use the mouse and keyboard.

Open it from a phone

Install the Tailscale app, sign in with the same account, and open the same address in the phone browser. The on-screen keyboard and the extra keys (Ctrl, Alt, Tab, Esc) live in the side panel of noVNC.

Hands for an agent

lsh-hands is a small VNC client in one file. An agent that already has a shell on that machine (a LogiShell terminal, or ssh) uses it to look at the screen and act on it.

lsh-hands size                          # width and height of the screen in pixels
lsh-hands shot ~/shot.png --scale 2     # a frame, half size
lsh-hands click 640 360 --scale 2       # coordinates of a frame at the same scale
lsh-hands click 100 200 --button right
lsh-hands click 100 200 --double
lsh-hands move 100 200
lsh-hands scroll 640 360 3              # above zero is down
lsh-hands type "some text"
lsh-hands key ctrl+c                    # enter, alt+tab, win+d, f5 ...
lsh-hands latency                       # ms from a pointer move to the screen answering

The working order for an agent is always the same: take a frame, look at it, act once, take a frame again. Clicking twice without looking in between is how an agent ends up in the wrong window.

The VNC password comes from the environment, never from a file:

LSH_VNC_PASSWORD='<your VNC password>' lsh-hands shot ~/shot.png --scale 2

If you keep secrets in Doppler, --secret <name of the secret> at install time makes lsh-hands fetch the value at the moment of the call. Only the name is stored on the machine.

Security

• The page listens on 127.0.0.1 only. From outside the single way in is Tailscale, and only for devices signed in to your network. If your network has other people or guest devices in it, narrow its access rules to your own devices.
• A VNC password is weak protection: the classic sign-in uses the first eight characters, and the page travels over plain http. Both are acceptable inside the Tailscale tunnel and nowhere else. Do not expose the VNC port or port 6080 to the open internet, and do not forward them on a router.
• The password is not stored in a file by the installer.

What is not here

• No switch on the machine and no log. Whoever reaches the port and knows the password sees the screen and can press on it. Nothing records who pressed what.
• No work zone. LogiShell's privacy profiles do not know about this road. Do not install it on a work machine or a client's machine.
• No button in the product. The screen opens by address in a browser. The machine's card in Settings → Devices says nothing about it.
• No sound, and no smooth motion in the browser view, see below.

Speed and quality

Numbers from one machine of ours (Windows 11 with WSL2, RTX 4060 Ti), measured on 12 October 2026. They are a measurement, not a promise: your network decides yours.

Measure your own road with lsh-hands latency: six pointer moves, the time until the screen answers each, and the median.

This is enough to open a window, press a button and type a line. VNC sends pictures of the parts of the screen that changed, so anything that moves (scrolling, video, dragging a window) looks blurred and jumps. That is how the protocol works, not a setting to tune.

Two things that help before you reach for anything else:

• check tailscale status on the device you watch from. direct is the fast road; relay adds a hop through a Tailscale server;
• look at what the machine is doing. Under load the same road was three times slower for us.

When you need smooth video

For anything that moves, use a video stream next to the browser view, over the same Tailscale network: Sunshine on the machine and Moonlight on the Mac or phone. On the machine above this gave 1920x1080 at 60 frames per second, encoded as HEVC on the graphics card.

1. Install Sunshine on the machine with the desktop and set a login in its web page, which opens on the machine itself.
2. Install Moonlight on the Mac or the phone.
3. In Moonlight add the machine by its Tailscale address. Moonlight shows a PIN; type it into the Sunshine page to pair.
4. Pick the desktop in Moonlight.

Two things to know. On Windows, Sunshine runs in Windows itself, so Tailscale has to be installed in Windows as well as in WSL; on our PC both joined the network and both connected directly. And the portable build of Sunshine does not show the Windows sign-in screen or permission prompts: for those, the browser view is still the one that works.

Keep both. The browser view needs nothing installed on the watching device and is what lsh-hands talks to. The video stream is for your eyes.

Tailscale or a Cloudflare tunnel

For a screen, Tailscale is the fit: it is the shorter path and it carries the UDP that a video stream needs. A Cloudflare tunnel suits a web page you want to open from a device where you cannot install anything. If you do put the screen page behind a tunnel, put an access gate in front of it first: without one, an eight character VNC password is all that stands between the internet and your keyboard.

Tailscale's plans, as their site listed them on 12 October 2026: Personal is free. Signing in with a company domain counts as a business account, which gets a 14 day trial and then needs a plan (Standard was 8 dollars per user per month). Prices change, so read tailscale.com/pricing before you count on any of this.

Remove it

sudo bash infra/remote-screen/install.sh --uninstall

This removes the service, the lsh-hands command, /opt/lsh-screen, and the Tailscale road if the installer opened it. It leaves the VNC server alone, because you installed that.

What comes next in the product

This page describes a side road that works today. The road LogiShell is building goes through the node you already paired, with no VNC and no second network to set up. What exists there now is one frame on request: Show screen on the machine's card in Settings → Devices. Still ahead, with no date attached:

• input (keyboard and mouse) through the node, behind a switch on the machine itself and with a log of who pressed what;
• hands for LOG, allowed by you for one session at a time;
• a video stream of our own, so that smooth motion does not need a second program.

The design is written down in the repository: docs/superpowers/specs/2026-09-24-remote-control-design.md. When input and the stream are built, this side road is removed with the --uninstall command above.