# NetDesk — your own self-hosted remote desktop

<p>
  <a href="https://netdesk.space"><img alt="Website" src="https://img.shields.io/badge/website-netdesk.space-19c87e"></a>
  <img alt="Version" src="https://img.shields.io/badge/version-1.5.0-blue">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Windows%20%7C%20Web%20%7C%20macOS%20(build)-lightgrey">
  <img alt="E2E" src="https://img.shields.io/badge/encryption-ECDH%20P--256%20%2B%20AES--256--GCM-orange">
</p>

**Website & live demo:** [netdesk.space](https://netdesk.space) · **Download:** [Windows agent](https://netdesk.space/download) · **Pricing:** [free to self-host](https://netdesk.space/pricing)

A TeamViewer/RustDesk-style remote desktop system you fully own: a signaling/relay
server for your VPS, a **Windows service** on your powerful PC (reachable at boot,
at the logon screen, and across UAC prompts), and a **zero-install web viewer**
(Chrome/Edge) you can use from any laptop or phone while traveling.

```
 ┌──────────────────────────┐  WSS outbound only  ┌──────────┐   WSS   ┌──────────────┐
 │ HOME PC (Windows service)│ ──────────────────► │  VPS     │ ◄────── │ TRAVEL laptop│
 │  broker (SYSTEM, boot)   │                     │  netdesk │         │ any browser  │
 │   └─ desktop agent       │ ◄──── relayed ────► │  server  │         │ (phone works)│
 │      (console session)   │  E2E-encrypted      └──────────┘         └──────────────┘
 └──────────────────────────┘
        │
        └──── optional direct mode: ws://home-ip:8901 (LAN / port-forward) ────┘
```

## Features

**Access & unattended operation**
- Boot-time Windows service (SYSTEM): no auto-logon needed, survives reboots
- Reachable at the **Windows logon screen** — view and type credentials to log in
- Input works across desktop switches (user desktop, logon screen, UAC prompts) via desktop-following injection
- Auto-reconnect to server forever (works behind any NAT, no port forwarding)
- Wake displays automatically when a viewer connects

**Video / audio**
- H.264 (x264 ultrafast/zerolatency), up to 1080p60 @ 20 Mbps, idle screens send nothing
- Hardware decode in the browser (WebCodecs) + HTML5 canvas
- Adaptive **Auto quality** mode (RTT/decoder-queue based preset stepping)
- System audio (WASAPI loopback → Opus) — bundled in the packaged exe; `pip install PyAudioWPatch` for source runs

**Full control**
- Mouse (all buttons, wheel), keyboard via SendInput scancodes, keyboard-lock for Alt+Tab/Win/Ctrl+W in fullscreen
- **Privacy mode** — turn the physical monitor off while you keep working
- **Lock PC on disconnect** (per-viewer checkbox)
- Process manager — list & kill remote processes
- Remote power — lock, sign out, reboot, shut down, run command
- Clipboard sync (two-way), chat

**Files**
- Browse/download/upload/rename/delete/mkdir, **folder upload** with drag & drop
- Atomic uploads (.part → final), folder creation on demand

**Security**
- **End-to-end encryption** (default): ephemeral ECDH P-256 → AES-256-GCM per frame — the VPS cannot see your screen
- Password never leaves the host un-hashed (PBKDF2 200k challenge/response, 0.4 s throttle per bad attempt)
- Optional **TOTP 2FA** (`--set-totp auto` → authenticator code required at connect)
- Optional server registration key so only your hosts can register; `/status` API behind a token
- The service broker relays opaque bytes only — agents hold all keys

**Accounts (RustDesk-style)**
- Sign up / sign in **in the desktop app and on the website** — no email
  verification wall (the account works immediately; the email only confirms it)
- **My computers**: every PC where you sign in with your account is listed on
  the website for one-click connect (online/offline/in-session status shown)
- Server address is **pre-filled** (netdesk.space) and no registration key is
  needed by default; point the app at your own server anytime
- Pre-configured builds: name the exe `NetDeskHost-host=your.server,key=SECRET.exe`
  and it auto-configures — hand it out with zero setup

**Viewer niceties**
- Address book (saved connections), remember-password, view-only mode
- **Session recording** to .webm (one click)
- **TCP tunneling** — reach any TCP service on the host (SSH, RDP, web UIs) through the server; portal-gated, with a panel in the viewer
- **Installable app (PWA)** — install the viewer like a native app from Chrome/Edge/Safari on laptop or phone
- **Host-side remote printing** — send a file to the host's printer from the file manager
- Multi-monitor switching, quality presets, live stats (fps/RTT/bitrate/E2E badge)

## Quick start (try on one PC)

```bat
cd path\to\netdesk
scripts\run_local_demo.bat
```

First run prints and saves a 9-digit ID and a random password
(`%APPDATA%\NetDesk\config.json`). Automated end-to-end test:
`.venv\Scripts\python tools\smoke_test.py` (23 checks: auth, 2FA, E2E video,
clipboard, processes, privacy, files, input, broker path…).

## Portable exe — a regular desktop app, no Python needed

`portable\` (and `..\NetDesk-portable-win64.zip`) ships standalone Windows x64
binaries built with PyInstaller, **tested end-to-end** (full 20-check suite
passes against the packaged exes):

| File | Purpose |
|---|---|
| `NetDeskHost.exe` (54 MB, windowed) | the agent **desktop app** — double-click it: a control panel opens with live status, your ID, server settings, password/2FA management, start/stop, and one-click service install |
| `NetDeskServer.exe` (14 MB, console) | server for a Windows VPS; serves the viewer **and the portal** |

Double-clicking `NetDeskHost.exe` opens the control panel (config + logs are
created next to the exe — the folder is fully portable). Advanced users can
still drive everything from a terminal (`--server …`, `--install`,
`--set-password`, `--set-totp auto`, `--uninstall`); the app itself is
windowless, so CLI output goes to `host.log` next to the exe. `--install`
sets up the same boot-time SYSTEM service with full logon-screen/UAC access.

## macOS (MacBook M4 / Apple Silicon and Intel)

Mac binaries cannot be cross-compiled from Windows, so the repo builds them ON
the Mac — native, one command:

```bash
git scp the netdesk folder to the Mac, then:
bash scripts/build_mac.sh        # -> dist/NetDeskHost + dist/NetDeskServer (arm64)
```

- `NetDeskHost` on the Mac = control the Mac remotely (capture via mss, input
  via CoreGraphics CGEvent, clipboard via pbpaste/pbcopy, process manager,
  power via osascript). First run: grant **Screen Recording** and
  **Accessibility** permissions (System Settings → Privacy & Security); if
  Gatekeeper complains: `xattr -cr NetDeskHost`.
- Autostart on login: `scripts/deploy/com.netdesk.host.plist` → copy to
  `~/Library/LaunchAgents/` (edit the path/server inside first),
  then `launchctl load ~/Library/LaunchAgents/com.netdesk.host.plist`.
- `NetDeskServer` also builds on the Mac if you want a Mac VPS.
- macOS audio capture needs a loopback device (e.g. BlackHole) — off by default.
- Connecting TO a Mac or PC from the MacBook: just the browser — open the
  server URL in Chrome/Edge/Safari; nothing to install.

## Web management portal

Start the server with `--portal-password "YourPortalPassword"` and open
`https://your-server:8443/portal` — a TeamViewer-console-style dashboard:

- **Computers list** — every host that ever registered, online/offline status,
  version, last-seen, and a **Connect** button that deep-links into the viewer
  (`/?id=<id>` — ID prefilled, just type the host password)
- **Live stats** — hosts online, sessions total, relayed traffic, uptime
- **Activity feed** — host online/offline, connect attempts, accepted sessions,
  wrong-password/2FA failures (auth failures are visible server-side; passwords
  never are)
- **Downloads** — anything you drop into the server's `files/` folder
  (e.g. `NetDeskHost.exe`) is offered to logged-in users, so your travel laptop
  can always grab the current agent from your own server

Access control: single portal password (cookie session, HttpOnly, 7 days).
The portal runs over the same TLS as everything else — keep TLS on for
internet use. By design the portal **cannot** see or store host passwords
(end-to-end encryption); connecting always needs the host's own password.

## Production setup

### 1. Server on your VPS (Debian/Ubuntu)

```bash
cd netdesk/scripts/deploy && sudo bash deploy_vps.sh   # installs systemd service, prints REG_KEY
# add --portal-password "..." to the unit for the web portal at /portal
sudo ufw allow 8443/tcp
```

TLS (recommended): Let's Encrypt via certbot, then add `--cert/--key` to the unit
and restart. Quick alternative: `--gen-cert` (self-signed, accept browser warning once).

### 2. Host on your powerful PC (twice, then forget it)

```bat
:: once, as your user: pick the password and server
.venv\Scripts\python host\netdesk_host.py --set-password "YourStrongPassword"
.venv\Scripts\python host\netdesk_host.py --server wss://desk.yourdomain.com:8443/ws --reg-key REG_KEY --listen 8901

:: once, as Administrator: install the boot-time service
scripts\install_autostart.bat        (runs: netdesk_host.py --install)
```

The installer copies credentials to `C:\ProgramData\NetDesk` and creates a
SYSTEM scheduled task (ONSTART) running the **broker**. The broker spawns a
**desktop agent** into your console session and re-spawns it on user switches.
Optional: `--set-totp auto` for a 2FA secret (print → add to your authenticator).
Optional: `pip install PyAudioWPatch` for remote sound.

### 3. Travel

Open `https://desk.yourdomain.com:8443/` — enter ID (+ 2FA code if enabled) and
password. Save it in the address book. Works on phones too. At the office logon
screen after a reboot? Connect and type your Windows password — you're in.

## Security model

TLS to the server + end-to-end AES-GCM media + PBKDF2 password proof + optional
TOTP + registration key. Single session per host; second viewer gets "host busy".
Everything is stateless on the VPS.

## Silent operation & what "undetected" means here

Like RustDesk 1.2, NetDesk is invisible on the host while you work:

- The engine is **headless** — no window, no tray icon, nothing pops up when a
  session starts. In service mode it runs as a hidden SYSTEM task from boot.
- **Privacy mode** turns the physical monitor off while you keep working.
  Enable **"Blank the monitor while controlled"** in the app (or per-session
  via the viewer's privacy button) and the screen goes dark the moment a
  viewer connects; it comes back when the session ends.
- Sessions inject input only; a person sitting at the PC would see the mouse
  move (true for RustDesk/TeamViewer too — blocking local input needs a driver).

Be honest about the detection surface, because "undetected" does not mean
"forensically invisible": the process shows in Task Manager, Windows sees the
scheduled task, the host keeps logs (`host.log`), and the machine makes an
outbound connection to your VPS. RustDesk has the same surfaces. That is the
correct trade-off for administering **your own or explicitly authorized
computers**; covertly controlling a machine you do not own or are not
authorized to manage is illegal in most jurisdictions and this tool is not
designed for it.

## Honest limitations

- No UDP P2P hole-punching: browsers can't send raw UDP, so traffic relays
  through your VPS (~1 extra RTT; same as RustDesk when its punch fails). Direct
  mode (`--listen` + port-forward) bypasses the VPS on your LAN.
- Remote printing is not implemented (needs a printer driver); use file transfer + local printing.
- True privacy mode (fake desktop) needs a virtual display driver — NetDesk turns
  the physical monitor off instead.
- Session-0 notes: input at the logon screen/UAC requires the service install
  (agent as SYSTEM). Ctrl+Alt+Del itself is never injectable without a driver.
- No mobile native apps (the web viewer works in phone browsers).

## Files

```
netdesk/
├── server/netdesk_server.py    # signaling + relay + web host (stateless)
├── server/web/                 # viewer UI
├── host/netdesk_host.py        # broker + desktop agent + service installer
├── tools/smoke_test.py         # 23-check end-to-end suite
├── scripts/                    # local demo, service install, VPS deploy
└── requirements.txt
```

## Troubleshooting

| Symptom | Fix |
|---|---|
| "host offline" | Broker not running: `schtasks /Run /TN NetDesk`, or start `--broker` manually; logs in the config folder's `host.log` |
| "bad 2FA code" | Host clock drift — resync Windows time, or re-set `--set-totp` |
| Black screen + "logon screen" banner | Nobody logged in — type credentials via keyboard, desktop switches automatically |
| Input dead on UAC prompt | Only in simple (non-service) mode — install the service for SYSTEM desktop access |
| Choppy | Auto quality preset, or direct mode on LAN |
| E2E badge missing | Old browser — needs WebCodecs + WebCrypto (Chrome/Edge 102+) |

## Get the source code

The full source is published on the project website (no GitHub account needed):

```bash
# Clone directly from netdesk.space
git clone https://netdesk.space/git/netdesk.git

# …or download a snapshot
#   https://netdesk.space/source   →  .tar.gz / .zip
```

## Repository layout

```
netdesk/
├── server/            Python aiohttp signaling + relay + web client
├── host/              Python Windows host/agent + desktop GUI (pywebview)
├── native/            from-scratch native client (Rust core + Flutter UI)
├── docker/            Dockerfile + compose for the server
├── scripts/ tools/    helper + maintenance scripts
└── requirements.txt   Python deps for the server/host
```

## License

Source-available — free to self-host and modify for your own use. See `LICENSE`.