RemoteX Agent

Share your screen instantly from any machine. No configuration, no installs (on Windows).

Quick Start

# Install and run in one command
npx remotex

# With custom relay server
npx remotex --relay-url http://your-relay-server:3001

That's it. You'll see your PC ID and PIN. Open the RemoteX viewer in a browser, enter them, and you're connected.

Features

• Zero dependencies on Windows - Uses only built-in PowerShell and .NET Framework
• Cross-platform - Also works on Linux and macOS (with available tools)
• High quality - Configurable JPEG quality (1-100)
• Smooth - Up to 60 FPS capture rate
• WebRTC upgrade path - Falls back to WebSocket, can upgrade to P2P

Installation

Option 1: npx (recommended, no install)

npx remotex

Option 2: Global install

npm install -g remotex
remotex

Option 3: Local install

npm install remotex
npx remotex

Usage

Usage: remotex [options]

Options:
  --id <id>          Custom PC ID (auto-generated if omitted)
  --pcid <id>        Alias for --id
  --pin <pin>        Custom PIN (auto-generated if omitted)
  --fps <number>     Frames per second for screen capture (default: 10)
  --quality <number> JPEG quality 1-100 (default: 80)
  --relay-url <url>  Relay server URL (default: http://localhost:3001)
  -h, --help         Show help
  -v, --version      Show version

Examples

# Default: auto-generate PC ID and PIN, connect to local relay
npx remotex

# Custom PIN (useful for recurring sessions)
npx remotex --pin mysecretpin

# Higher quality / framerate
npx remotex --quality 90 --fps 30

# Connect to a remote relay server (e.g., on a VPS)
npx remotex --relay-url https://your-relay.example.com

# Custom PC ID (easier to remember)
npx remotex --id MYDESKTOP --pin secure123

# Use a specific relay server and higher settings
npx remotex --relay-url http://192.168.1.100:3001 --fps 30 --quality 85

Platform-Specific Notes

Windows

No additional software needed. Uses PowerShell + .NET Framework (built into Windows).

• Screen capture via System.Drawing + Graphics.CopyFromScreen
• Mouse/keyboard via SendInput Win32 API
• DPI-aware (Per-Monitor DPI v2)

Works on Windows 10 and 11. PowerShell must be allowed to run scripts (-ExecutionPolicy Bypass is used automatically).

Linux

Requires one of these screenshot tools (install via your package manager):

# Pick one:
sudo apt install grim          # Wayland (recommended)
sudo apt install scrot         # X11 (recommended)
sudo apt install imagemagick   # X11 (import command)
sudo apt install gnome-screenshot  # GNOME
sudo apt install spectacle     # KDE

For input injection:

# Wayland:
sudo apt install ydotool
sudo systemctl enable --now ydotoold   # auto-start on boot

# X11:
sudo apt install xdotool

macOS

Requires no additional software. Uses built-in screencapture command.

Architecture

Your Machine (remotex agent)          Relay Server           Viewer (Browser)
       |                                    |                       |
       |-- TCP socket.io ------------------>|<------ socket.io ---->|
       |                                    |                       |
       |<---- viewer input events ----------|---------------------->|
       |                                    |                       |
       |-- JPEG frame --------------------->|------ JPEG frame ---->|
       |                                    |                       |
       (can upgrade to WebRTC P2P)          |                       |

Frames are streamed from agent to viewer via the relay server. The relay never stores frames - it just fans them out to connected viewers.

Troubleshooting

Black screen on Windows

• Make sure the relay server is running
• Check that PowerShell can execute scripts (-ExecutionPolicy Bypass is used automatically)
• Try a lower FPS: npx remotex --fps 5

Input not working on Windows

• UAC dialogs may block input injection
• Some applications (games, password managers) may intercept keystrokes
• Try running the viewer as a standard user

Linux: "No screenshot tool found"

• Install one of: grim, scrot, imagemagick
• On Wayland: grim is the most reliable
• On X11: scrot is the most reliable

Linux: ydotool not working

1. Make sure ydotoold daemon is running: pgrep ydotoold
2. If not running: sudo ydotoold &
3. Add yourself to the input group: sudo usermod -aG input $USER then log out/in

Viewer shows "Waiting for remote feed"

• Agent may not be connected to the same relay server as viewer
• Check the relay URL matches
• Verify the PC ID and PIN are correct

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TEMP (Windows) | Temp directory for scripts | C:\Temp | | TMPDIR (macOS/Linux) | Temp directory for frames | /tmp |

Security

• Sessions expire after 8 hours automatically
• PIN is required to connect (auto-generated or custom)
• Maximum 2 concurrent viewers per session
• Rate limiting on the relay server (prevents brute-force PIN attacks)
• No data is stored on the relay server after session ends

License

MIT