WhyKnot Handoff

Operator guide

Start a session, open tools, keep the host in control.

Handoff is built for short Windows help sessions where the host can see what is happening, approve riskier actions, and expose local TCP services without opening inbound firewall rules.

01

Download

Get the current Windows binary from the relay.

Invoke-WebRequest https://handoff.whyknot.dev/dl/handoff.exe -OutFile .\handoff.exe
02

Start

Run the host bridge from a PowerShell window the host can watch.

.\handoff.exe new
03

Share

Give the operator the view URL printed by the bridge. The host keeps the bridge window open until the session is done.

view: https://handoff.whyknot.dev/v/n1_...
04

Assist

The operator queues allowlisted commands from the browser. Mutating commands are marked and trigger the host warning gate on first use.

sys.info
net.ping target=example.com
ps.exec script="Get-Service"

Tunnel workflow

Reach a host-local service through an approved bridge.

Use the Tunnels panel when the host has a local web UI, API, or diagnostic port that the operator needs to inspect. The request appears on the host first; after approval, the operator runs handoff.exe tunnel <connect-token> with a short-lived token.

  1. Enter the host port in the viewer, for example 8080.
  2. Wait for the host to approve the tunnel.open prompt.
  3. Run the generated command on the operator computer.
  4. Open the printed local address while the tunnel command stays running.
PowerShell operator 
# Connect to the approved host tunnel
Invoke-WebRequest -Uri "https://handoff.whyknot.dev/dl/handoff.exe" -OutFile ".\handoff.exe"
.\handoff.exe tunnel tk_8S7Q2P --local-port 47800
Start-Process "http://127.0.0.1:47800"

Risk gate

Commands such as file writes, deletes, service control, process termination, Pico flashing, and arbitrary PowerShell require a host-side yes/no prompt once per session.

Tunnel boundary

Tunnels are session-scoped, single-purpose, and close when the operator disconnects, the host bridge exits, or either side closes the tunnel.

Session boundary

Closing the host bridge ends command execution. Tokens are session-scoped and the relay only accepts known Handoff command kinds.

Direct markdown

The repo guide is still available at /USAGE.md for plain-text reading and quick copy workflows.