peek

Docs

peek is a remote desktop for your own machines that connects instantly. The machine runs a small host that stays idle until you look; any browser is the client. It is meant for the times you want another computer's screen for a few seconds, where a five-second connect would be most of the wait.

How it works

Numbers

What matters for a quick look is how long the screen takes to appear, so that is what peek is built around. All at medium quality.

Over Tailscale

From a Linux laptop to a Windows desktop (one 1920×1200 screen) on another network, connected directly with a ping of 8 to 16 ms, peek 0.3.0 started with --keep-gpu. Two passes of 20 connections from idle, and one straight after the last connection:

MedianSlowest 10%
Connect to an idle machine, until the whole first frame (304 KB) has arrived135–151 ms191–215 ms
The same within 5 seconds of the last connection, capture still set up125 ms154 ms
Of that, capturing and encoding the full screen6.2 ms7.8 ms
Socket open (TLS and WebSocket handshakes answered)41–55 ms50–62 ms

Most of the rest is carrying the frame: the more detail on the screen, the bigger it is and the longer it takes. Without --keep-gpu, starting from idle took 191–210 ms on this machine.

On the machine itself

A Linux laptop (niri, one 1920×1080 screen) connecting to its own peek (0.3, with Vitals on and Power off, as installed), so these are peek's own share of the wait:

MedianSlowest 10%
Connect to an idle machine, until the whole first frame (198 KB) has arrived22 ms24 ms
The same within 5 seconds of the last connection, capture still set up12 ms15 ms
Of that, capturing and encoding the full screen8.1 ms11 ms
Socket open (WebSocket handshake answered)1.3 ms1.8 ms

While nobody is looking, peek captures nothing: over two idle minutes, peek and its Vitals process used 20 ms of CPU time (0.02% of a core) and held 18 MB of memory between them. The program is 4.6 MB.

The browser then takes a few milliseconds to decode and draw the frame. To see your own total, open Stats: First frame is the time from connecting to the screen drawn in your browser. To repeat these measurements, run bun bench/first-frame.ts from the repository (its header says how).

Set up a machine

1. Tailscale

Install Tailscale on the machine and on every device you will view it from, all on the same tailnet. Then, once per tailnet, in the Tailscale admin console under DNS, turn on HTTPS Certificates. (This puts your machine and tailnet names in the public Certificate Transparency logs.)

2. Install peek

peek is on npm, for Windows x64 and for Linux x64 and arm64. With Node installed:

npm install -g @peculiarnewbie/peek

bun add -g @peculiarnewbie/peek and pnpm add -g @peculiarnewbie/peek work too. Node only starts peek; the package carries the program itself.

To try it first without installing anything, run npx @peculiarnewbie/peek pair and go on to Pair a browser. peek then runs in that terminal until you close it.

3. Start it at logon

peek install --no-token

This copies peek to a fixed place and starts it in the background whenever you log in. Flags after install are for that peek; --no-token means only Tailscale connections are accepted.

Windows asks once for administrator rights: peek is allowed through Windows Firewall (Tailscale addresses only) and started hidden and as administrator, so it can also control windows that run as administrator. On a desktop PC, add --keep-gpu to connect faster from idle: peek then keeps its GPU device open while nobody is watching. It costs some memory, and on a laptop it can keep a separate graphics card from sleeping, so it is off by default.

Windows, at the login screen too: peek install --service --no-token runs peek as a Windows service instead. It then also shows the login screen, the lock screen and UAC prompts and takes input there, and keeps running while nobody is signed in, so a paired browser can do there whatever someone at the keyboard could. Turn on Run unattended in Tailscale's settings on that PC, or Tailscale disconnects while nobody is signed in. peek install without --service goes back; either way your paired browsers keep working.

Linux: run it from inside the Wayland session. It becomes a systemd user service that starts with the graphical session. Keys are typed through /dev/uinput, which many distributions already let the logged-in user write; the README has the one-line udev rule if yours does not.

After updating (npm update -g @peculiarnewbie/peek), run peek install again with the same flags. peek uninstall removes it. To build from source instead, see the README.

Pair a browser

On the machine, run:

peek pair

The first time, it sets up Tailscale Serve so browsers can reach the machine over HTTPS (Tailscale may ask you to allow that, or on Linux for sudo tailscale set --operator=$USER). If peek is not running yet, it starts peek in that terminal, which keeps it running until you close it. Then it prints a link and a QR code with a one-time code, valid once, for five minutes. Then either:

A browser already connected to the machine can pair another device too: Settings → Pair a device shows a QR code.

Tailscale Serve's usual HTTPS port, 443, can go to only one app on a machine. If another app has it, peek pair says so and leaves it alone. peek pair --serve-port 8443 (or 10000) puts peek on another port instead. The machine's name then includes the port, like my-pc.tail1234.ts.net:8443, and the link and code from then on carry it.

In Chrome, allow Local network access when the site asks. Without it Chrome blocks the page from reaching your machines.

Using it

Open a machine from your list. Its page has its own address (for example /screen/my-pc), so it can be bookmarked; the toolbar's back button returns to the list. Hover the dot at the top for the toolbar.

Apps and plugins

A machine can offer more than its screen. Three apps come with peek; only Vitals is on from the start:

An app with a page of its own, like Files, gets a button in the toolbar.

Plugins add apps of your own. Settings → Manage plugins installs one from a folder on the machine, a .tgz, an HTTPS git address or an npm name, and starts, stops, updates and removes it without restarting peek. The same can be done on the machine:

peek plugin add <source>     # a folder, an https git address, or an npm package
peek plugin list             # everything beside the screen, and whether it is on
peek plugin update <name>
peek plugin remove <name>    # --purge also deletes what it kept

A plugin is a program that runs with peek's rights (SYSTEM under the Windows service), so install only ones you trust. To keep paired browsers from installing, removing or changing plugins, run peek plugin remote-install off on the machine; they can then still turn plugins on and off. To write one, see the plugin contract and the page protocol.

Every machine at once

Plugins, beside Machines at the top of your list, shows which plugins each machine has: By plugin, one row per plugin with the machines it is on, or Grid, machines by plugins. From there you can turn a plugin on or off on any machine, install one on a machine that lacks it from where another machine got it (an HTTPS git address or npm), and update an older copy. It asks before installing or updating, and says what the plugin will run. A machine's name opens its own Plugins page, for settings and for installing something new.

On the list of machines, each card shows its plugins: solid when on, dashed when off. Pick a plugin above the list to compare: a card where it is off or missing offers to turn it on or install it. A machine needs peek 0.3.1 or newer to show up here.

On a phone or tablet

Tap the dot for the toolbar. Its Trackpad / Touch button switches how a finger works:

GestureTrackpad (default)Touch
One finger movingmoves the pointerdrags
Tapleft click at the pointerleft click there
Long pressholds the left button: move to dragright click
Two-finger tapright clickright click
Three-finger tapmiddle clickmiddle click
Two fingers movingscrollscroll
Pinchzoom around the pointerzoom and pan

The bar at the bottom is the keyboard. Type in its field with the phone's keyboard, then Send types it on the machine in one go. The keyboard button beside it swaps in a PC keyboard with Ctrl, Alt, Win, Shift, F-keys and arrows.

Paired browsers

On the machine:

peek clients        # list the browsers paired with it
peek unpair <id>    # unpair one; it can no longer connect

On this site, the × on a machine forgets it in this browser. Pairing it again needs a new code.

Security

Troubleshooting

"Cannot reach" a machine

Seeing what peek is doing

On the machine, peek logs shows what peek logged recently (connections, capture starts, errors), even when it runs in the background; peek logs -f keeps following it.

"No longer paired"

The machine unpaired this browser, or its pairing data was reset. Run peek pair there again.

Everything else, including every option and how peek works inside, is in the README on GitHub.