The only official and verified release of PortDesk is hosted at:
👉 https://github.com/Lucky-abdo/PortDesk
Copies or forks obtained from third-party websites, messaging groups, or unofficial links may have been modified. We cannot guarantee that such versions retain the same privacy standards, security model, or integrity as the original. Please exercise caution and always verify the source before running any code on your machine.
here is an prompt so ai concises it.
summary this file ,so i know how to install and run it and the important notices on the tool ,and no more than thatPortDesk turns any device into a full PC controller over your local network (WiFi or USB).
No installation needed — just open a URL in any browser.
Everything runs locally on your machine. Nothing is sent to the internet. Ever.
(and adb but its optional)
python -m pip install -r requirements.txt**better run it by start file
** run gen cert so the server runs on https rather than http
python gen_cert.py # generates cert.pem and key.pem **portdesk-server.py auto-detects the certificates and starts HTTPS
You'll see something like:
══════════════════════════════════════════════════
🎮 PortDesk v1.0
══════════════════════════════════════════════════
[USB] adb reverse tcp:5000 tcp:5000 → http://localhost:5000
[WiFi] http://192.168.1.x:5000
══════════════════════════════════════════════════
-
WiFi: Open
http://192.168.1.x:5000in any browser on any device on the same network and Accept warning in the browser if showen. -
USB (Android): Run
adb reverse tcp:5000 tcp:5000first, then openhttp://localhost:5000
Docker is recommended for Linux users who want to run PortDesk without installing Python or any dependencies manually.
Not suitable for Windows or macOS — PortDesk needs direct access to your screen, keyboard, and mouse, which Docker can only provide properly on Linux.
docker run -d \
--network=host \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
--device /dev/snd \
luckyabdo/portdesk:latestThen open http://localhost:5000 in your browser or on any device on the same network.
-
Connect your device and PC to the same WiFi network ** make sure it's the main wifi network, not guest either data wifi
-
Open the IP shown in the terminal on any browser
-
Works from phones, tablets, laptops, other PCs — anything with a browser
-
Slight latency possible over WiFi
Requires ADB (Android Debug Bridge) installed on PC.
# Enable USB Debugging on your Android device first, then:
adb reverse tcp:5000 tcp:5000Then open http://localhost:5000 on your device.
For non-Android devices (iPhone, iPad, laptop) just use WiFi mode — USB mode is Android-specific.
**USB mode may occur some latency.
- Move finger = move mouse
- Tap = left click
- Long press = right click
- Two fingers = scroll
- Scroll buttons on the side
Press the 🌀 Gyro button to use your device's physical tilt (mobile/tablet) as mouse movement.
- Calibrate (🎯): Sets the current phone angle as "center"
- Sensitivity: Adjustable in Settings
- Dead Zone: Minimum tilt before movement registers
Press 🧠 AI to enable the AI sensitivity calibration system.
It watches how you move and automatically adjusts gyro sensitivity and dead zone to match your natural hand movement style.
The more you use it, the more accurate it gets.
Your learned profile is saved in the browser and survives page refreshes.
Reset it anytime from Settings → AI Gesture Reset.
Pre-built keyboard shortcuts organized by category:
- System: Copy, Paste, Undo, Redo, Select All, Save, Cut, Search
- Windows: Alt+Tab, Win+D (Desktop), Win+L (Lock), Alt+F4, Win+E, Task Manager, Screenshot, Task View
- Media: Play/Pause, Next, Previous, Mute, Volume Up/Down
Dedicated controls for PowerPoint / Google Slides:
- Start / End slideshow
- Next / Previous slide
- Arrow keys, Black screen, White screen
Customizable gamepad layout with two controller types: PS and Xbox.
Profiles: Create multiple profiles for different games. Long-press a profile to delete it.
Full Mode 🎮: Hides all UI and shows only the controller canvas in fullscreen. Tap "Exit Gaming Mode" to return.
Editor (✏️): Customize button layout:
- Hold & drag a button from the Palette (top bar) onto the canvas
- Tap a placed button to select it
- Long press a placed button to assign a key/shortcut to it
- Drag the resize handle (bottom-right) to resize
- Tap ✕ to remove a button
Camera Wheel: A special circular control in the palette (⊙) that renders as a steering wheel. Use it for camera control in 3D games — drag your finger to push the wheel in any direction and it continuously moves the mouse.
Stats (📊): Shows CPU usage, temperature, and RAM usage in real-time while gaming.
Mirror your PC screen to your device.
- Adjust resolution, quality, FPS
- Multi-monitor support
- Cursor color customization
- Touchpad and keyboard available while viewing
Requires
opencv-pythonorPillow. For best performance installopencv-python.
Browse, manage, and transfer files between your device and PC.
- Navigate: Tap folders to open, tap files to download
- Breadcrumb: Shows current path, tap any part to jump back
- Sort: By name, date, size, or type
- Select: Tap items to select, then Download / Delete
- Upload: Tap the Upload button to send files from your device to the PC
- New folder / New file: Buttons in the toolbar
- Long press or right-click any item for the context menu:
- Copy, Cut, Paste
- Rename
- Create Shortcut
- Properties
- Delete
Record and replay sequences of actions.
- Tap ⏺ Record
- Add steps: Click, Key, Type text, or Wait
- Give it a name and tap 💾 Save
- Tap ▶ Run to execute it anytime
Macros are saved on the PC in portdesk_macros.json.
View running processes, sorted by CPU usage. Tap ⛔ to terminate any process.
Enable Auto for live refresh every 3 seconds.
Schedule macros to run at specific times.
- Pick a time
- Name the task
- Select a macro
- Tap + Add
Enable/disable individual tasks with the toggle. The server checks every 10 seconds.
Two views:
- Server: Events logged by the server (connections, pin attempts, audio start/stop, etc.)
- Client: Real-time JavaScript log from your device — useful for debugging
- Touch sensitivity, gyro sensitivity, dead zone, scroll speed
- Haptic feedback, sound feedback
- Auto-sleep timer
- PIN lock
- Backup & restore settings (JSON export/import)
- Whitelist management
- AI reset
- Light/Dark theme
- Language (Arabic / English)
- Remote Audio (requires VB-Audio on Windows)
- Mobile Microphone
PortDesk is designed for local network use only. It has a built-in IP whitelist system.
How it works:
- When a new device tries to connect over WiFi, the server prints a prompt in the terminal asking you to allow or deny it
- Type
yto add the device to the whitelist,nto reject - The whitelist is saved in
portdesk_security.json - Whitelisted devices connect automatically in the future
Manage the whitelist from the phone:
- Settings → Add this device to whitelist (sends approval request to server console)
- Settings → Remove myself from whitelist (removes only your own device)
- A device rejected 3 times from the server console is automatically blacklisted
- The server owner can remove a device from the blacklist via localhost only
PIN Lock:
- Settings → Set PIN — set a 4-digit PIN
- Anyone opening the URL must enter it before accessing the controller
- PIN is stored as a salted SHA-256 hash in the browser, never sent to the server in plain text
- After 5 wrong attempts, the server locks the IP with an escalating lockout: 60 seconds on the 1st lockout, 180 seconds on the 2nd, and 300 seconds (fixed) from the 3rd onward
Streams your PC's audio to your device in real-time.
Windows: Requires VB-Audio Virtual Cable.
Set your app's audio output to "CABLE Input". PortDesk reads from "CABLE Output".
Linux: Uses PulseAudio — no extra software needed.
Uses your device's microphone as a virtual mic on the PC.
Windows: Requires VB-Audio Virtual Cable. PortDesk outputs to "CABLE Input".
Requires HTTPS (see HTTPS setup above).
| Feature | Windows | Linux | macOS |
|---|---|---|---|
| Mouse & Keyboard | ✅ | ✅ | ✅ |
| Screen Mirroring | ✅ | ✅ | ✅ |
| CPU Temperature | ✅ CoreTemp | ✅ via psutil | ✅ powermetrics |
| Win/Meta shortcuts | ✅ | ✅ | ✅ |
| Remote Audio | ✅ VB-Audio | ✅ PulseAudio | |
| Mobile Mic | ✅ VB-Audio | ✅ | |
| File Shortcuts (.lnk) | ✅ | .desktop | symlink |
- Screen mirroring FPS depends on your network speed and PC performance
- Install
pyturbojpegfor significantly better screen streaming performance:pip install pyturbojpeg - Python 3.14 is not supported — use Python 3.11 or 3.12
- Mobile microphone requires HTTPS (generate a certificate first)
- Remote audio on macOS has limited support
- Gyroscope on iOS requires user permission (browser will ask on first use)
- Win key shortcuts (Win+D, Win+L, etc.) may not work if the server terminal window has focus — minimize it or use the
.batlauncher
| File | Description |
|---|---|
portdesk-server.py |
The Flask server — run this on your PC |
portdesk_client.html |
The phone UI — served automatically by the server |
gen_cert.py |
Generates self-signed SSL certificate for HTTPS |
requirements.txt |
Python dependencies |
portdesk_security.json |
Whitelist & blacklist (auto-created, not in repo) |
portdesk_macros.json |
Saved macros (auto-created) |
portdesk_scheduled.json |
Scheduled tasks (auto-created) |
portdesk_events.log |
Server event log (auto-created) |
MIT License — see LICENSE
PortDesk was built with the assistance of AI tools. This is mentioned in the spirit of transparency — the architecture, decisions, and direction were by me, but AI was used throughout the development process for code generation, debugging, and documentation.