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
- Set up a machine
- Pair a browser
- Using it
- Apps and plugins
- On a phone or tablet
- Paired browsers
- Security
- Troubleshooting
How it works
- The host runs on Windows, or on Linux under a Wayland compositor with the wlroots protocols (niri, sway, Hyprland, river). It captures the screen only while a client is watching.
- This site serves the page and nothing else. Your browser connects straight to each machine over
Tailscale, at its
https://<machine>.<tailnet>.ts.netname. - The list of your machines and the keys for them stay in your browser. Nothing about them is sent to or stored on this site.
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:
| Median | Slowest 10% | |
|---|---|---|
| Connect to an idle machine, until the whole first frame (304 KB) has arrived | 135–151 ms | 191–215 ms |
| The same within 5 seconds of the last connection, capture still set up | 125 ms | 154 ms |
| Of that, capturing and encoding the full screen | 6.2 ms | 7.8 ms |
| Socket open (TLS and WebSocket handshakes answered) | 41–55 ms | 50–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:
| Median | Slowest 10% | |
|---|---|---|
| Connect to an idle machine, until the whole first frame (198 KB) has arrived | 22 ms | 24 ms |
| The same within 5 seconds of the last connection, capture still set up | 12 ms | 15 ms |
| Of that, capturing and encoding the full screen | 8.1 ms | 11 ms |
| Socket open (WebSocket handshake answered) | 1.3 ms | 1.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:
- open the link on the device you want to use, or scan the QR code with its camera (on Android Chrome, Scan QR code on this site works too), or
- on this site, choose Add a machine and enter the machine's name and the code.
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.
- Sleep stops the screen while keeping the connection; click the page or press Space to resume. Pause when unfocused in Settings does this whenever the window is in the background.
- Settings has presets (Saver, Balanced, Crisp), and quality, resolution, motion, frame rate and monitor on their own.
- Stats shows frame rate, data rate and latency.
- Mouse, keyboard and clipboard go through as on the machine itself.
Apps and plugins
A machine can offer more than its screen. Three apps come with peek; only Vitals is on from the start:
- Vitals: processor, memory and storage, as a line on the machine's card in your list and as figures in Stats.
- Power (Windows): Sleep on the machine's card, and Wake while it is asleep. A sleeping machine runs nothing, so another paired machine on the same network sends the Wake-on-LAN packet; Sleep is offered only while one is online and the machine has a wired card Windows lets wake it. The first sleep is a test: the machine is woken 15 seconds later, and the card says what to check if it was not. Off by default: turn it on under Settings → Manage plugins on the machine to sleep and on the one that wakes it, which can be a Linux machine.
- Files: browse folders you choose on the machine and download from them. It is read-only and off by default: turn it on and pick its folders under Settings → Manage plugins.
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:
| Gesture | Trackpad (default) | Touch |
|---|---|---|
| One finger moving | moves the pointer | drags |
| Tap | left click at the pointer | left click there |
| Long press | holds the left button: move to drag | right click |
| Two-finger tap | right click | right click |
| Three-finger tap | middle click | middle click |
| Two fingers moving | scroll | scroll |
| Pinch | zoom around the pointer | zoom 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
- Machines are reached only over Tailscale, so your tailnet decides which devices can get to them at all.
- From this site, a machine accepts only browsers paired with it. Each browser has its own key; the machine keeps only a hash of it.
- Pairing codes work once, for five minutes, and guessing is rate-limited.
- A plugin runs with peek's rights on the machine. Install only ones you trust;
peek plugin remote-install offkeeps browsers from installing them (see Apps and plugins). - Never expose peek's port with
tailscale funnel: that would put it on the internet.
Troubleshooting
"Cannot reach" a machine
- Check that Tailscale is connected on this device and that the machine is on.
- Check that peek is running there and that
peek pairset up Tailscale Serve (tailscale serve status). - In Chrome, check the site may access your local network: the icon left of the address bar.
- The very first connection to a machine can take a few seconds while Tailscale fetches its certificate.
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.