guides · how-to
Tips and tricks
Shortcuts, diagnostics, and the handful of behaviours that surprise people — collected from actually running this thing.
Keyboard shortcuts
While the mouse is captured, your keystrokes go to the host. These chords are held back for the client window itself, so they always work:
| Chord | Does |
|---|---|
| Click the stream | Capture mouse and keyboard |
Ctrl + Alt + Shift + Z | Release mouse and keyboard |
Ctrl + Alt + Shift + X | Toggle fullscreen |
Ctrl + Alt + Shift + S | Toggle the statistics overlay |
Ctrl + Alt + Shift + C | Copy the host’s clipboard to this machine |
Ctrl + Alt + Shift + V | Send this machine’s clipboard to the host |
Ctrl + Alt + Shift + F | Open file transfer |
Ctrl + Alt + Shift + D | Run diagnostics (press again to cancel) |
Ctrl + Alt + Shift + 1…9 | Switch to the host’s Nth display |
Z is the one to memorise — it hands your mouse and keyboard back if input ever feels stuck. Think Z for zurück, or just remember it sits next to nothing else you’ll press by accident.
C and V follow copy/paste from your machine’s point of view: C fetches the host’s clipboard to you, V sends yours to the host.
One more, for the beta only
| Chord | Does |
|---|---|
Ctrl + Alt + Shift + R | Force the video layer to re-composite |
This is a diagnostic, not a feature, and it exists only while the beta runs. It forces a no-op window frame-refresh to make the compositor re-attach the video layer if it has dropped it mid-stream — the cause of a black picture that persists while the session is otherwise healthy.
If you hit a black screen during a live session, press it. Two useful outcomes either way: if the picture comes back, that tells us a frame-refresh is enough and the recovery can be made automatic; if it doesn’t, the fix needs to be something heavier. Either result is worth reporting — it’s the single most useful thing you can tell us about a black screen.
Expect it to disappear from a stable release once the underlying recovery is automatic.
Read the statistics overlay before changing anything
Ctrl + Alt + Shift + S puts live numbers on screen. When a session feels wrong, this tells you which thing is wrong — and the causes want opposite fixes:
- Latency high, bitrate fine — a network path problem. Check whether you’re relayed rather than connected directly.
- Bitrate far below what you asked for — the host clamped it. Look at the encoder’s max bitrate in the admin panel; the client can only ask.
- Picture smears briefly after a stall — packet loss. Expected on Wi-Fi, and it repairs itself within a frame rather than waiting for a keyframe.
Guessing without the overlay usually means changing the setting that wasn’t the problem.
When the overlay isn’t enough: run the diagnostics
Ctrl + Alt + Shift + D (Windows client, in a session) runs a scripted diagnostic test of about two and a half minutes against the host. It changes one thing at a time — filler traffic with no video to test the link alone, a moving test pattern in place of your desktop at several bitrates, a deliberately discarded frame to time the recovery, a flood of keyframe requests — and ends with a report that says which stage is the limit: the link, the host, or this client’s decoder.
For most of the run you see the test pattern rather than your desktop. Press the chord again to cancel; the stream goes back to normal either way.
The report is two files, summary.md (the verdict, with each measurement beside the limit it was judged against) and records.jsonl (every number behind it). It is saved on the client under %APPDATA%\NearZero\diagnostics\ and sent to the host automatically, where it lands in diagnostics\ inside the host’s data folder. A host can switch the feature off with [diagnostics] enabled = false in host_config.toml.
The keyboard belongs to the host
Keys travel as positions, not letters, and the host’s keyboard layout decides what they type. A German host types z where a US host types y, for the same physical key — exactly as if you were sitting at it.
This is deliberate, and it’s the same model RDP uses. If you’re getting unexpected characters, change the layout on the host; changing it on your client does nothing.
You will not re-pair when your address changes
Pairing pins the host’s identity, not its address. Move between home Wi-Fi, a tailnet and a café, and the client recognises the same host and quietly remembers the new address alongside the old.
So if a client asks you to pair again, something is actually wrong — usually a rotated host identity or a wiped config directory — rather than a normal consequence of changing networks.
Pick a display; don’t always take the canvas
The display picker’s last entry composites every attached monitor into one spanning image. That’s the right answer for “I need to see everything”, and the wrong default for focused work: your bitrate spreads across the whole canvas, so three 1440p monitors at 20 Mbps look considerably worse than one 1440p monitor at 20 Mbps.
Switch with Ctrl + Alt + Shift + 1…9 mid-session — no reconnect needed.
Leave the connection password on wan
scope = wan challenges clients arriving from outside your LAN and stays out of your way at home. That’s the default for a reason: it covers the borrowed-laptop-somewhere-else case without making you type a password to reach the machine in the next room.
Tailscale counts as WAN here, which is usually what you want.
Watching is a role, not a permission
When several clients hold a session, exactly one drives and the rest watch — and the host enforces that, refusing input and every state-changing request rather than merely hiding buttons in their UI.
But everyone in that session already paired with the host. Don’t hand a pairing token to somebody you only want watching. For a host that never admits a second client, set max_watchers to 0.
Curtain hides the room, not the session
Curtain mode blanks the host’s monitors so nobody walking past can read your screen. Two things it does not do:
- It doesn’t hide anything from other clients on the session — watchers keep seeing everything.
- It isn’t a lock. Local keyboard and mouse still reach the desktop underneath. Lock the machine as well if that matters.
Where the logs are
The host writes C:\ProgramData\NearZero\logs\host.<date>.log (readable without an administrator prompt; right-click the tray icon → Open logs folder); the Windows client writes client.<date>.log in its own config directory. The last 14 days are kept and older files are deleted automatically.
The log is the best runtime truth available — it records what the host actually negotiated, which is often more useful than what a settings page says should have happened. When reporting a problem, the log beats a description of it.
The tray icon is a status light
Grey is idle, green is a connected client, red is an error. If a client can’t connect and the tray is grey, the host never saw it — look at the network path or the address you typed, not at the host’s settings.
Check the version line after an upgrade
The first thing the host logs is what it actually is:
nearzero-host listening version="0.9.x (3eb3a7f)" protocol=3 listen=0.0.0.0:48010 ...Host and client must be on the same line, the leftmost non-zero number (0.9 here); the rest of their numbers need not match. Different lines fail at the handshake with a message saying so rather than misbehaving, but when something is inexplicably broken after an upgrade, checking this line on both ends is the fastest way to rule it in or out.