yuanyuanxiang/SimpleRemoter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Release v1.3.4

Browse Source
This commit is contained in:
yuanyuanxiang
2026-05-20 15:15:08 +02:00
parent d808462fe1
commit 6e743ada0b
14 changed files with 889 additions and 1592 deletions
Download Patch File Download Diff File Expand all files Collapse all files

806
ReadMe_EN.md
View File

@@ -12,9 +12,9 @@
<a href="https://github.com/yuanyuanxiang/SimpleRemoter/releases">
<img src="https://img.shields.io/github/v/release/yuanyuanxiang/SimpleRemoter?style=flat-square" alt="GitHub Release">
</a>
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue?style=flat-square" alt="Platform">
<img src="https://img.shields.io/badge/language-C%2B%2B17-orange?style=flat-square&logo=cplusplus" alt="Language">
<img src="https://img.shields.io/badge/IDE-VS2019%2B-purple?style=flat-square&logo=visualstudio" alt="IDE">
<img src="https://img.shields.io/badge/client-Windows%20%7C%20Linux%20%7C%20macOS-blue?style=flat-square" alt="Client Platforms">
<img src="https://img.shields.io/badge/server-Windows%20%7C%20Linux%20%7C%20macOS-success?style=flat-square" alt="Server Platforms">
<img src="https://img.shields.io/badge/language-C%2B%2B17%20%2F%20Go-orange?style=flat-square&logo=cplusplus" alt="Language">
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
</p>
@@ -29,10 +29,7 @@
> [!WARNING]
> **Important Legal Notice**
>
> This software is intended **solely for educational purposes and authorized use cases** such as:
> - Remote IT administration within your own organization
> - Authorized penetration testing and security research
> - Personal device management and technical learning
> This software is intended **solely for educational purposes and authorized use cases**: remote IT administration within your own organization, authorized penetration testing and security research, personal device management, and technical learning.
>
> **Unauthorized access to computer systems is illegal.** Users are fully responsible for compliance with all applicable laws. The developers assume no liability for misuse.
@@ -41,12 +38,13 @@
## Table of Contents
- [Overview](#overview)
- [Disclaimer](#disclaimer)
- [What's New: Full-Platform Loop Closed](#whats-new-full-platform-loop-closed)
- [Compliance & Anti-Abuse](#compliance--anti-abuse)
- [Features](#features)
- [Technical Highlights](#technical-highlights)
- [Cross-Platform Support](#cross-platform-support)
- [Architecture](#architecture)
- [Getting Started](#getting-started)
- [Client Support](#client-support)
- [User Documentation](#user-documentation)
- [Changelog](#changelog)
- [Related Projects](#related-projects)
- [Contact](#contact)
@@ -55,62 +53,83 @@
## Overview
**SimpleRemoter** is a full-featured remote control solution, rebuilt from the classic Gh0st framework using modern C++17. Started in 2019, it has evolved into an enterprise-grade remote management tool supporting **Windows, Linux, and macOS** platforms.
**SimpleRemoter** is an end-to-end cross-platform remote control solution.
### Core Capabilities
The project is built on the classic **Gh0st architecture** and was first started in January 2019. After 7 years of continuous iteration — from rebuilding the IOCP communication core, video-grade x264 encoding, the V2 file transfer protocol, the multi-layer authorization model, all the way to the introduction of Linux and macOS clients — this release finally completes **the full-platform loop for both client and server**: all three major desktop operating systems (Windows / Linux / macOS) can act as either the controlled side or the master side.
| Category | Features |
|----------|----------|
| **Remote Desktop** | Real-time screen control, multi-monitor support, H.264 encoding, adaptive quality |
| **File Management** | Bi-directional transfer, resumable uploads, C2C transfer, SHA-256 verification |
| **Terminal** | Interactive shell, ConPTY/PTY support, modern web terminal |
| **System Management** | Process/service/window management, registry browsing, session control |
| **Media Capture** | Webcam monitoring, audio listening, keylogging |
| **Networking** | SOCKS proxy, FRP tunneling, port forwarding |
### Use Cases
- **Enterprise IT Operations**: Batch management of intranet devices, remote troubleshooting
- **Remote Work**: Secure access to office computers, file synchronization
- **Security Research**: Penetration testing, red team exercises, security audits
- **Technical Learning**: Network programming, IOCP model, encrypted transmission practice
**Original Source:** [zibility/Remote](https://github.com/zibility/Remote) | **Started:** 2019.1.1
**Original source:** [zibility/Remote](https://github.com/zibility/Remote) | **Started:** 2019.1.1
[![Star History Chart](https://api.star-history.com/svg?repos=yuanyuanxiang/SimpleRemoter&type=Date)](https://star-history.com/#yuanyuanxiang/SimpleRemoter&Date)
---
## Disclaimer
## What's New: Full-Platform Loop Closed
**Please read the following statement carefully before using this software:**
The **C++ MFC master** (`YAMA.exe`) has been the project's core delivery form for years — classic Gh0st architecture, high-performance IOCP core, the complete remote desktop / file / process / media feature stack, multi-layer authorization, brand customization — and **remains the primary master to this day**. The MFC master also ships with a built-in WebSocket-based Web Remote Desktop service: since v1.3.1, **a browser on any platform** (phone / tablet / Linux / macOS desktop) can remote-control managed devices through it.
1. **Lawful Use**: This project is intended solely for legitimate technical research, educational exchange, and authorized remote management. It is strictly prohibited to use this software for unauthorized access to others' computer systems, data theft, privacy surveillance, or any other illegal activities.
This release (v1.3.4) adds the last missing piece — the **Go master**: a **deliberately small, focused server** centered on *remote desktop + remote terminal + multi-user roles*, compiled and running across Windows / Linux / macOS. It is **not a replacement for the MFC master**. It exists for users who **cannot reasonably run a Windows VPS** and still want a native Linux / macOS landing point — for example pure Linux servers, always-on ARM Macs, or embedded master appliances.
2. **User Responsibility**: Users must comply with the laws and regulations of their country/region. Any legal liability arising from the use of this software shall be borne by the user.
### Which Master Should You Use
3. **No Warranty**: This software is provided "as is" without any express or implied warranties, including but not limited to warranties of merchantability or fitness for a particular purpose.
| Form | GUI | Feature coverage | Platform | Role |
|---|---|---|---|---|
| **C++ MFC Master** (`YAMA.exe`) | Native Windows GUI + built-in Web service | ✅ **All features** | Windows | **Recommended.** Daily operations, file management, media capture, multi-layer licensing, branding — all of these go through MFC |
| **Go Master** (new) | Web UI (any browser) | Remote desktop + remote terminal + multi-user | Windows / Linux / macOS | **Supplementary.** For zero-Windows-dependency Linux / macOS master deployments |
4. **Limitation of Liability**: The developers shall not be liable for any direct, indirect, incidental, special, or consequential damages arising from the use, misuse, or inability to use this software.
> [!TIP]
> Both masters **speak to the exact same client binaries** — you can mix and match: e.g. one Windows MFC master + one Linux Go master managing the same fleet of devices in parallel.
5. **Copyright Notice**: This project is open-sourced under the MIT License, allowing free use, modification, and distribution, provided that the original copyright notice is retained.
### Go Master Capabilities (v1.3.4)
**By continuing to use this software, you acknowledge that you have read, understood, and agreed to all the above terms.**
- **Remote Desktop**: H.264 piped over WebSocket to the browser, hardware-decoded via WebCodecs, smooth 1080P @ 20fps
- **Remote Terminal**: xterm.js + ConPTY/PTY, with resize and Tab-completion support
- **Multi-user**: admin / regular user roles, Challenge-Response login, opaque tokens, per-device-group authorization
- **Production deployment**: Nginx reverse proxy + Let's Encrypt + Keyboard Lock + fullscreen handling that prevents accidental ESC / F11 exit
- **Intentionally minimal**: no file management, no media capture, no registry, no service management — those remain MFC-master features
### Full Platform Support Matrix
| | **Client (controlled)** | **Master** |
|---|---|---|
| **Windows** | ✅ All features | ✅ MFC `YAMA.exe` (recommended) / Go |
| **Linux** (X11) | ✅ Screen + terminal + files + clipboard | ✅ Go |
| **macOS** (Intel + Apple Silicon) | ✅ Screen + terminal + files + clipboard | ✅ Go |
---
## Compliance & Anti-Abuse
This project takes a deliberate "explicit compliance posture". This release tightens the anti-abuse boundary further.
### Built-in Technical Measures
Multiple independently verifiable anti-abuse barriers are constructed at the source-code level. See the [Anti-Abuse Technical Measures Inventory](./docs/Compliance_TechnicalMeasures.md) for the full catalog:
- **Inbound IP range check**: trial builds deployed to the public Internet trip a visible warning latch
- **Listening port cap**: trial builds are limited to ≤ 2 listening ports, blocking multi-tenant relay conversion
- **Application-layer RTT anti-proxy**: LAN-only RTT thresholds detect reverse proxies / tunnels
- **Multi-layer authorization**: V2 ECDSA offline + V1 online + trial — each tier has independent limits
- **Web master authentication**: enforced Challenge-Response login, login rate limiting, opaque tokens, auditable operations
### Compliance Documents
| Document | Content |
|---|---|
| 📖 [Anti-Abuse & Compliance Policy](./docs/Compliance_AntiAbuse.md) | Full publisher / user responsibility allocation |
| 📖 [Anti-Abuse Technical Measures Inventory](./docs/Compliance_TechnicalMeasures.md) | Source-code location, design motivation, known limitations of each barrier |
> [!IMPORTANT]
> **Network Connection & Privacy Notice**
>
> The master program (server) communicates with the authorization server based on license status:
>
> | License Type | Connection Behavior |
> |--------------|---------------------|
> | Trial Version | Maintains persistent connection to authorization server |
> | V1/V2 Licensed | Connects at startup for verification, disconnects after |
> | V2 Offline License | No connection to authorization server required |
>
> Unless offline authorization is obtained, the master program will exchange necessary data with the authorization server (e.g., detecting cracking attempts, validating license status).
>
> **By using this software, you accept the data transmission between the master program and the authorization server. If you do not agree, please do not use this software.**
> **Using this software constitutes acknowledgment that you have read, understood, and accepted all terms in the above compliance documents.** If you do not or cannot accept any term, stop using the software immediately and destroy all copies in your possession.
### Network & Privacy
| License type | Connection behavior |
|---|---|
| Trial | Maintains a persistent connection to the authorization server |
| V1 / V2 licensed | Connects at startup for verification, disconnects after |
| V2 offline license | No connection to the authorization server required |
Unless an offline license has been obtained, the master program exchanges necessary data with the authorization server (e.g. detecting cracking attempts, validating license status).
---
@@ -120,604 +139,313 @@
![Remote Desktop](./images/Remote.jpg)
- **Multiple Capture Methods**: GDI (high compatibility), DXGI (high performance), Virtual Desktop (background operation)
- **Smart Compression Algorithms**:
- DIFF algorithm - SSE2 optimized, transmits only changed regions
- RGB565 algorithm - 50% bandwidth savings
- H.264 encoding - Video-level compression for high frame rate scenarios
- Grayscale mode - Minimal bandwidth consumption
- **Adaptive Quality**: Automatically adjusts frame rate (5-30 FPS), resolution, and compression based on network RTT
- **Multi-Monitor**: Support for screen switching and multi-screen wall display
- **Privacy Screen**: Hide controlled screen, supports control during lock screen
- **File Drag & Drop**: Ctrl+C/V cross-device copy and paste files
- **Web Remote Desktop**: Access remote desktop via browser, supports mobile/tablet ([Configuration Guide](./docs/WebHTTPS.md))
- **Multiple screen capture backends**: GDI / DXGI / virtual desktop (Windows), X11 + XShm (Linux), CGDisplayStream (macOS)
- **Smart compression**: DIFF (SSE2-optimized) / RGB565 (50% bandwidth savings) / **H.264** (video-grade, via x264 + VideoToolbox + WebCodecs) / grayscale mode
- **Adaptive quality**: framerate (5–30 FPS), resolution, and compression algorithm adjusted automatically based on RTT
- **Multi-monitor**: monitor switching + multi-monitor wall display
- **Cross-device file drag-and-drop**: copy/paste files across devices with Ctrl+C / Ctrl+V
- **Web Remote Desktop**: browser-based access, mobile-ready ([config guide](./docs/WebHTTPS.md))
![Web Remote Desktop](./images/WebRemote.png)
### File Management
![File Management](./images/FileManage.jpg)
- **V2 Transfer Protocol**: Newly designed, supports large files (>4GB)
- **Resumable Transfer**: Automatic recovery after network interruption, persistent state
- **C2C Transfer**: Direct transfer between clients without going through master
- **Integrity Verification**: SHA-256 hash verification ensures file integrity
- **Batch Operations**: Supports file search, compression, batch transfer
- **V2 transfer protocol**: large files (>4 GB), resumable transfers, SHA-256 verification
- **C2C transfer**: client-to-client direct transfer without going through the master
- **Bulk operations**: search, compress, batch transfer
### Terminal Management
### Terminal
![Terminal](./images/Console.jpg)
![Console Management](./images/LinuxClient.png)
- **Interactive Shell**: Full command line experience with Tab completion
- **ConPTY Technology**: Native pseudo-terminal support for Windows 10+
- **Modern Web Terminal**: Based on WebView2 + xterm.js (v1.2.7+)
- **Terminal Resizing**: Adaptive window size
### Process & Window Management
| Process Management | Window Management |
|-------------------|-------------------|
| ![Process](./images/Process.jpg) | ![Window](./images/Window.jpg) |
- **Process Management**: View process list, CPU/memory usage, start/terminate processes
- **Code Injection**: Inject DLL into target process (requires admin privileges)
- **Window Control**: Maximize/minimize/hide/close windows
### Media Features
| Video Management | Audio Management |
|-----------------|------------------|
| ![Video](./images/Video.jpg) | ![Audio](./images/Voice.jpg) |
- **Webcam Monitoring**: Real-time video stream, adjustable resolution
- **Audio Listening**: Remote sound capture, bi-directional voice support
- **Keylogging**: Online/offline recording modes
- **Interactive shell**: Tab completion, ANSI escape sequences, resizable
- **Modern terminals**: ConPTY on Windows, PTY on Linux / macOS
- **Web terminal**: xterm.js + WebSocket, parity with the native experience
### Other Features
- **Service Management**: View and control Windows services
- **Registry Browsing**: Read-only browsing of registry contents
- **Session Control**: Remote logout/shutdown/restart
- **SOCKS Proxy**: Establish proxy tunnel through client
- **FRP Tunneling**: Built-in FRP support for easy intranet penetration
- **Code Execution**: Remote DLL execution with hot update support
| Module | Capability |
|---|---|
| **Process management** | Process list, CPU / memory usage, kill, DLL injection |
| **Window management** | Maximize / minimize / hide / close |
| **Media capture** | Webcam, two-way voice, keylogger |
| **System control** | Service management, registry, session logoff / shutdown |
| **Networking** | SOCKS proxy, FRP tunneling, port forwarding |
| **Code execution** | Remote DLL execution, in-memory loading, hot update |
---
## Technical Highlights
## Cross-Platform Support
### High-Performance Network Architecture
### Windows Client
```
┌─────────────────────────────────────────────────────────┐
│ IOCP Communication Model │
├─────────────────────────────────────────────────────────┤
│ • I/O Completion Ports: Most efficient async I/O on │
│ Windows │
│ • Single master supports 10,000+ concurrent connections │
│ • Supports TCP / UDP / KCP transport protocols │
│ • Auto-chunking for large packets (max 128KB send buf) │
└─────────────────────────────────────────────────────────┘
```
**Requirements**: Windows 7 SP1 or later
**Feature completeness**: ✅ All features supported
### Adaptive Quality Control
### Linux Client (v1.2.5+)
Intelligent quality adjustment system based on RTT (Round-Trip Time):
**Requirements**:
- Display server: X11/Xorg (Wayland not yet supported)
- Required: libX11. Recommended: libXtst (XTest extension), libXss (idle detection)
| RTT Latency | Quality Level | FPS | Resolution | Compression | Use Case |
|-------------|---------------|-----|------------|-------------|----------|
| < 30ms | Ultra | 25 FPS | Original | DIFF | LAN office |
| 30-80ms | High | 20 FPS | Original | RGB565 | General office |
| 80-150ms | Good | 20 FPS | ≤1080p | H.264 | Cross-network/Video |
| 150-250ms | Medium | 15 FPS | ≤900p | H.264 | Cross-network office |
| 250-400ms | Low | 12 FPS | ≤720p | H.264 | Poor network |
| > 400ms | Minimal | 8 FPS | ≤540p | H.264 | Very poor network |
| Feature | Status | Implementation |
|---|---|---|
| Remote desktop | ✅ | X11 capture + libx264 H.264 hardware encoding |
| Remote terminal | ✅ | PTY interactive shell |
| File management | ✅ | V2 protocol, bidirectional, large files |
| Process management | ✅ | List + kill |
| Clipboard sync | ✅ | xclip / xsel external tools, supports file URIs |
| Heartbeat / RTT | ✅ | RFC 6298 RTT estimation |
| Daemon mode | ✅ | Double-fork daemonization |
- **Zero Overhead**: Reuses heartbeat packets to calculate RTT
- **Fast Downgrade**: Triggers after 2 detections, responds to network fluctuations
- **Cautious Upgrade**: Quality improves only after 5 stable readings
- **Cooldown Mechanism**: Prevents frequent switching
**Build**: `cd linux && cmake . && make`
### V2 File Transfer Protocol
### macOS Client (v1.3.2+)
```cpp
// 77-byte protocol header + filename + data payload
struct FileChunkPacketV2 {
uint8_t cmd; // COMMAND_SEND_FILE_V2 = 85
uint64_t transferID; // Transfer session ID
uint64_t srcClientID; // Source client ID (0=master)
uint64_t dstClientID; // Destination client ID (0=master, C2C)
uint32_t fileIndex; // File index (0-based)
uint32_t totalFiles; // Total file count
uint64_t fileSize; // File size (supports >4GB)
uint64_t offset; // Current chunk offset
uint64_t dataLength; // Current chunk data length
uint64_t nameLength; // Filename length
uint16_t flags; // Flags (FFV2_LAST_CHUNK, etc.)
uint16_t checksum; // CRC16 checksum (optional)
uint8_t reserved[8]; // Reserved for extension
// char filename[nameLength]; // UTF-8 relative path
// uint8_t data[dataLength]; // File data
};
```
**Requirements**:
- macOS 10.15 (Catalina) or later
- Architecture: Intel (x64) and Apple Silicon (arm64) universal binary
- Permissions: Screen Recording, Accessibility, Full Disk Access
**Features**:
- Large file support (uint64_t breaks 4GB limit)
- Resumable transfer (state persisted to `%TEMP%\FileTransfer\`)
- SHA-256 integrity verification
- C2C direct transfer (client to client)
- V1/V2 protocol compatibility
| Feature | Status | Implementation |
|---|---|---|
| Remote desktop | ✅ | CGDisplayStream + VideoToolbox H.264 hardware encoding |
| Mouse / keyboard | ✅ | CGEvent, supports double-click and drag |
| Remote terminal | ✅ | PTY interactive shell (zsh/bash) |
| File management | ✅ | V2 protocol, large files |
| Process management | ✅ | proc_listpids + kill |
| Clipboard sync | ✅ | NSPasteboard, file URLs + NSFilenamesPboardType |
| Daemon mode | ✅ | `-d` background mode, power management, idle detection |
### Screen Transmission Optimization
**Build**: `cd macos && ./build.sh`
- **SSE2 Instructions**: Hardware-accelerated pixel difference calculation
- **Multi-threaded Parallel**: Thread pool for chunked screen data processing
- **Scroll Detection**: Identifies scrolling scenarios, reduces bandwidth by 50-80%
- **H.264 Encoding**: Based on x264, GOP control, video-level compression
### Go Master (v1.3.4+)
### Security Mechanisms
**Requirements**: Go 1.21+ (build time only); binary runs without dependencies
| Layer | Measures |
|-------|----------|
| **Transport Encryption** | AES-256 data encryption with configurable IV |
| **Authentication** | Signature verification + HMAC authentication |
| **Authorization Control** | Serial number binding (IP/domain), multi-level authorization |
| **File Verification** | SHA-256 integrity verification |
| **Session Isolation** | Session 0 independent handling |
| Capability | Implementation |
|---|---|
| Remote desktop | H.264 → WebSocket → WebCodecs, 1080P @ 20fps |
| Remote terminal | xterm.js + PTY/ConPTY transparent forwarding |
| Multi-user | Challenge-Response + opaque token + per-group authorization |
| Deployment | Nginx reverse proxy / Let's Encrypt / systemd unit / `/etc/environment` |
### Dependencies
| Library | Version | Purpose |
|---------|---------|---------|
| zlib | 1.3.1 | General compression |
| zstd | 1.5.7 | High-speed compression |
| x264 | 0.164 | H.264 encoding |
| libyuv | 190 | YUV conversion |
| HPSocket | 6.0.3 | Network I/O |
| jsoncpp | 1.9.6 | JSON parsing |
**Build**: `cd server/go && go build -o server_linux_amd64 ./cmd`
---
## Architecture
### Cross-Platform Topology
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Multi-Layer Authorization Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ Super Admin │ │
│ │ (Authorization │ │
│ │ Server) │ │
│ └─────────┬───────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ V2 License │ V2 License │ V2 License │
│ │ (ECDSA) │ (ECDSA) │ (ECDSA) │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Layer-1 A │ │ Layer-1 B │ │ Layer-1 C │ ◄── Independent │
│ │ │ │ │ │ │ & Isolated │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ ┌────────┴────────┐ │ ┌──────┴──────┐ │
│ │ V1 License │ │ │ V1 License │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ... ┌──────────┐ ┌──────────┐ │
│ │ Sub A1 │ │ Sub A2 │ │ Sub C1 │ │ Sub C2 │ │
│ │ Master │ │ Master │ │ Master │ │ Master │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Clients │ │ Clients │ │ Clients │ │ Clients │ │
│ │ 10,000+ │ │ 10,000+ │ │ 10,000+ │ │ 10,000+ │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ License Type Verification Features │
│ ───────────────────────────────────────────────────────────────────────── │
│ V2 License ECDSA P-256 Signature Offline verify, connection limits │
│ V1 License HMAC + Online Verify Connects to upstream server │
│ Trial Online Verify Limited features, always connected │
└─────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ Master Layer │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ C++ MFC Master │ │ Go Master │ │
│ │ YAMA.exe │ │ (Win/Linux/Mac) │ │
│ │ Windows only │ │ Web UI, all OS │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
└────────────┼──────────────────────────┼─────────────────┘
│ │
│ TCP (custom binary proto)│ TCP (devices) + WS (browsers)
└────────┬─────────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Windows │ │ Linux │ │ macOS │
│ client │ │ client │ │ client │
│ (DXGI) │ │ (X11) │ │ (CG) │
└─────────┘ └─────────┘ └─────────┘
```
### Architecture Advantages
### Multi-Layer Authorization (simplified view)
| Feature | Description |
|---------|-------------|
| **Hierarchical Control** | Super user manages any master, supports unlimited tiers |
| **Complete Isolation** | Different Layer-1 users have isolated licenses, data, and clients |
| **Independent Operation** | Layer-1 users can set pricing, issue licenses, build their brand |
| **Horizontal Scaling** | Single master supports 10,000+ clients, multi-layer scales to millions |
| **Offline Support** | V2 license supports full offline verification, no upstream dependency |
```
Super Admin (authorization server)
│ V2 license (ECDSA P-256)
▼
Layer-1 Master ──┬── Layer-1 Master ──┬── Layer-1 Master ◄── independent / fully isolated
│ V1 │ V1 │ V1
▼ ▼ ▼
Sub-master → Clients (10,000+) → Device fleet
```
### Master Program (Server)
| License | Verification | Notes |
|---|---|---|
| V2 license | ECDSA P-256 signature | Offline verification, sub-master connection cap |
| V1 license | HMAC + online check | Connects to upstream for verification |
| Trial | Online check | Feature- and connection-limited (see [compliance docs](./docs/Compliance_AntiAbuse.md)) |
The master program **YAMA.exe** provides a graphical management interface:
![Main Interface](./images/Yama.jpg)
- High-performance server based on IOCP
- Client group management
- Real-time status monitoring (RTT, geolocation, active window)
- One-click client generation
### Controlled Program (Client)
![Client Generation](./images/TestRun.jpg)
**Runtime Forms**:
| Type | Description |
|------|-------------|
| `ghost.exe` | Standalone executable, no external dependencies |
| `TestRun.exe` + `ServerDll.dll` | Separate loading, supports in-memory DLL loading |
| Windows Service | Background operation, supports lock screen control |
| Linux Client | Cross-platform support (v1.2.5+) |
| macOS Client | Cross-platform support (v1.3.2+) |
Full description: [Multi-Layer License](./docs/MultiLayerLicense.md)
---
## Getting Started
### 5-Minute Quick Start
### 5-Minute Walkthrough
No compilation required, download and run:
No compilation required — download and run:
1. **Download Release** - Get the latest version from [Releases](https://github.com/yuanyuanxiang/SimpleRemoter/releases/latest)
2. **Launch Master** - Run `YAMA.exe` and enter the license info (see trial license below)
3. **Generate Client** - Click the "Generate" button in the toolbar, configure server IP and port
4. **Deploy Client** - Copy the generated client to the target machine and run it
5. **Start Control** - Once the client comes online, double-click to open remote desktop
1. **Download a release** — grab the latest build from [Releases](https://github.com/yuanyuanxiang/SimpleRemoter/releases/latest)
2. **Start the master** — run `YAMA.exe` (or `server_linux_amd64` on Linux), enter the license info
3. **Generate a client** — click *Build* in the toolbar, configure server IP / port
4. **Deploy the client** — copy to the target machine and run it
5. **Take control** — once the client is online, double-click to open the remote desktop
> [!TIP]
> For initial testing, run both master and client on the same machine using `127.0.0.1` as the server address.
> For the first test, run both the master and the client on the same machine using `127.0.0.1` as the server address.
### Build Requirements
### Go Master Deployment (VPS)
- **Operating System**: Windows 10/11 or Windows Server 2016+
- **Development Environment**: Visual Studio 2019 / 2022 / 2026
- **SDK**: Windows 10 SDK (10.0.19041.0+)
### Build Steps
See the [Web Remote Desktop config](./docs/WebHTTPS.md). The minimum recipe:
```bash
# 1. Clone the repository (must use git clone, do not download as zip)
git clone https://github.com/yuanyuanxiang/SimpleRemoter.git
# 1. Run the Go master on the VPS
nohup ./server_linux_amd64 --port 6543 --http-port 9001 > yama.log 2>&1 &
# 2. Open the solution
# Open SimpleRemoter.sln with VS2019+
# 2. nginx reverse proxy: 9001 → HTTPS
# See docs/WebHTTPS.md
# 3. Select configuration
# Release | x86 or Release | x64
# 4. Build
# Build -> Build Solution
# 3. Open https://yourdomain.com/ in a browser, log in, add clients
```
**Common Issues**:
- Dependency library conflicts: [#269](https://github.com/yuanyuanxiang/SimpleRemoter/issues/269)
- Non-Chinese system garbled text: [#157](https://github.com/yuanyuanxiang/SimpleRemoter/issues/157)
- Compiler compatibility: [#171](https://github.com/yuanyuanxiang/SimpleRemoter/issues/171)
### Trial License (v1.2.4+)
### Deployment Methods
#### Intranet Deployment
Master and clients are on the same LAN, clients connect directly to master IP:Port.
#### Internet Deployment (FRP Tunneling)
A trial credential is provided — 2-year validity, 20 concurrent connections, LAN-only:
```
Client ──> VPS (FRP Server) ──> Local Master (FRP Client)
```
For detailed configuration, please refer to: [Reverse Proxy Deployment Guide](./反向代理.md)
### Authorization
Starting from v1.2.4, a trial password is provided (2-year validity, 20 concurrent connections, intranet only):
```
Authorization: Bound by computer IP
Master IP: 127.0.0.1
Serial: 12ca-17b4-9af2-2894
Password: 20260201-20280201-0020-be94-120d-20f9-919a
Verification: 6015188620429852704
Valid: 2026-02-01 to 2028-02-01
Master IP : 127.0.0.1
Serial : 12ca-17b4-9af2-2894
Password : 20260201-20280201-0020-be94-120d-20f9-919a
Token : 6015188620429852704
Valid : 2026-02-01 to 2028-02-01
```
> [!NOTE]
> **Multi-Layer Licensing**
>
> SimpleRemoter uses an enterprise-grade multi-layer authorization architecture, supporting independent operation for agents/developers:
> - **Offline Verification**: First-layer users can operate completely offline after obtaining authorization
> - **Independent Control**: Your downstream users connect only to your server, with data fully under your control
> - **Free Customization**: Supports secondary development to create your own branded version
>
> 📖 **[View Full Licensing Documentation](./docs/MultiLayerLicense.md)**
> Supports independent operation by resellers / developers: Layer-1 users can operate fully offline once licensed, and their sub-users only connect to *your* server. Full description: [Multi-Layer License](./docs/MultiLayerLicense.md)
### Build
- **C++ master & Windows client**: open `SimpleRemoter.sln` in VS 2019 / 2022 / 2026 → Release | x64
- **Linux client**: `cd linux && cmake . && make`
- **macOS client**: `cd macos && ./build.sh`
- **Go master**: `cd server/go && go build ./cmd`
---
## Client Support
## User Documentation
### Windows Client
**System Requirements**: Windows 7 SP1 and above
**Feature Completeness**: ✅ All features supported
### Linux Client (v1.2.5+)
**System Requirements**:
- Display Server: X11/Xorg (Wayland not yet supported)
- Required: libX11
- Recommended: libXtst (XTest extension), libXss (idle detection)
**Feature Support**:
| Feature | Status | Implementation |
|---------|--------|----------------|
| Remote Desktop | ✅ | X11 screen capture, mouse/keyboard control |
| Remote Terminal | ✅ | PTY interactive shell |
| File Management | ✅ | Bi-directional transfer, large file support |
| Process Management | ✅ | Process list, terminate processes |
| Heartbeat/RTT | ✅ | RFC 6298 RTT estimation |
| Daemon Process | ✅ | Double fork daemonization |
| Clipboard | ⏳ | In development |
| Session Management | ⏳ | In development |
**Build Instructions**:
```bash
cd linux
cmake .
make
```
### macOS Client (v1.3.2+)
**System Requirements**:
- macOS 10.15 (Catalina) or later
- Architecture: Universal Binary (Intel x64 + Apple Silicon arm64)
- Required permissions: Screen Recording, Accessibility, Full Disk Access
**Feature Support**:
| Feature | Status | Implementation |
|---------|--------|----------------|
| Remote Desktop | ✅ | CoreGraphics screen capture, VideoToolbox H.264 hardware encoding |
| Mouse Control | ✅ | CGEvent simulation, supports double-click, drag |
| Keyboard Control | ✅ | CGEvent simulation, full keycode mapping |
| Cursor Sync | ✅ | Real-time remote cursor style synchronization |
| Remote Terminal | ✅ | PTY interactive shell (zsh/bash) |
| File Management | ✅ | Bidirectional transfer, V2 protocol, large file support |
| Heartbeat/RTT | ✅ | RFC 6298 RTT estimation |
| Group Management | ✅ | Persistent configuration file |
| Process Management | ⏳ | In development |
| Clipboard | ⏳ | In development |
**Build Instructions**:
```bash
cd macos
./build.sh
# Or manually:
# mkdir build && cd build && cmake .. && make
```
| Document | Audience | Content |
|---|---|---|
| 📖 [Quick Start Guide](./docs/QuickStart.md) | First-time users | First-time deployment in 10 minutes |
| 📖 [Multi-Tier Network Setup](./docs/NetworkSetup.md) | Users managing sub-tiers | Multi-tier network architecture |
| 📖 [User Manual](./docs/UserManual.md) | All users | Complete feature walkthrough |
| 📖 [Reseller Operations Manual](./docs/AgentManual.md) | Resellers / distributors | Sub-licensing, FRP setup |
| 📖 [Customization Guide](./docs/CustomizationGuide.md) | Technical customers | Branding, secondary development |
| 📖 [Web Remote Desktop Setup](./docs/WebHTTPS.md) | Mobile / Go-master users | HTTPS reverse proxy, domain config |
| 📖 [Anti-Abuse Policy](./docs/Compliance_AntiAbuse.md) | All users | Compliance boundaries, responsibility allocation |
| 📖 [Anti-Abuse Technical Measures](./docs/Compliance_TechnicalMeasures.md) | Compliance auditors | Source-code location and motivation for each barrier |
---
## Changelog
### v1.3.3 (2026.5.10)
### v1.3.4 (2026.5.20)
**Linux/macOS Client Maturation & Two-Layer Auth & Cross-Platform Code Refactor**
**Go master & full-platform master loop & Linux/macOS clipboard**
**New Features:**
- **Server Identity Verification (Layer 1)**: Linux/macOS clients verify server via HMAC-SHA256; unauthorized server cannot trigger any sub-connection
- **Sub-Connection Auth (Layer 2, TOKEN_CONN_AUTH)**: All sub-connections sign first packet + clientID pinned, eliminates NAT/127.0.0.1 routing mismatches
- **Linux Client**: H.264 hardware encoding (dynamic libx264 loading), XFixes cursor type detection, UTF-8 protocol capability bit
- **macOS Client**: File manager, remote terminal (shared PTYHandler), clipboard sync, daemon mode (-d), power management, screen lock/idle detection, CGDisplayStream push-mode optimization
- **Master**: Screen preview thumbnail, region screenshot, remote desktop zoom, Web user group filtering, embedded modern terminal, adaptive screen algorithm, external resource override, group name persistence, Build Dialog support for generating macOS client
**Refactor:**
- Linux/macOS client shared code extracted to `common/` (rtt_estimator / client_auth_state / posix_net_helpers / sub_conn_thread), ~300 lines duplication removed
**New features:**
- **Go master**: cross-platform lightweight master service in Go (Windows / Linux / macOS), focused on *remote desktop + remote terminal + multi-user roles* — does not replace the MFC master, fills the gap for pure Linux/macOS deployments
- **Web remote desktop (Go master)**: H.264 → WebSocket → WebCodecs decode, 1080P @ 20fps, desktop + mobile; remote cursor sync, Keyboard Lock to prevent accidental ESC/F11 exit, F11/Esc passed through to the remote when in control mode
- **Web remote terminal (Go master)**: xterm.js + PTY/ConPTY transparent forwarding, resize, automatic terminal panel cleanup on disconnect
- **Multi-user (Go master)**: admin / regular user roles, per-device-group authorization, Challenge-Response login, login rate limiting (per-IP + per-username), opaque tokens
- **Linux client clipboard**: bidirectional clipboard sync via xclip / xsel, supports `text/uri-list` file paths
- **macOS client clipboard**: bidirectional clipboard sync via NSPasteboard, file URLs + legacy API compatibility
**Improvements:**
- Modern Terminal SYSTEM compatibility: auto fallback to classic terminal with precise reason in info list
- `build.ps1` adds `vswhere` fallback (finds VS installed on non-default drives)
- Force `/source-charset:utf-8 /execution-charset:.936` to fix Chinese garbling when compiling on English Windows
- macOS `install.sh` source binary priority optimized (command-line → script dir → build/bin), better suits distribution scenarios
- Web session adaptive quality is clamped to H264-only levels (≥ Good); Ultra/High (DIFF/RGB565) would otherwise leave the browser unable to decode
- Linux client default `QualityLevel` changed to `QUALITY_GOOD` (matching Windows / macOS) — no longer requests adaptive on the server side
- Login text fields decoded as UTF-8 / GBK depending on client capability bits, fixing mojibake in German / French hostnames and geo locations
- Device list now sorts stably (by online time), no longer reshuffles on every heartbeat / WS push
- RDP reset button wired through to `CMD_RESTORE_CONSOLE` on the device
- MFC master no longer briefly flashes its dialog when a Web session opens (session detection moved to the top of `OnInitDialog`)
**Bug Fixes:**
- V2 file transfer broken in both directions in FileManager dialog (upload IP routing errors + download chunks not dispatched)
- Modern Terminal blank under SYSTEM (WebView2 does not support LocalSystem)
- Linux client UTF-8 path/active-window garbled on server
- Log list header click incorrectly sorted host list
- Header sort broken after LVM_SETUNICODEFORMAT (HDN_ITEMCLICKW mapping added)
- Tray icon not showing in Release service+agent mode
- macOS/Linux clients did not resend LOGIN_INFOR after group change
- File dialog map dangling pointer crashes
- Reconnect crash from not clearing callback before destruction
- MFC and Web remote desktop sessions not fully independent
- macOS locked screen: display not woken on remote desktop start
- MFC remote desktop touchpad two-finger scroll not working
**Bug fixes:**
- After closing a Web session from fullscreen, device-list clicks became unresponsive (browser fullscreen subtree rule, now exited centrally in `showPage`)
- When a client crashed, the Web remote desktop page stayed on "Connected" forever (new `device_offline` notification)
- Multi-monitor polling caused two screen sub-connections to push frames simultaneously, making the picture flip between monitors (old sub-conn now retired in `BindScreenConn`)
- Go master `ListDevices` order was randomized by map iteration
### v1.3.3 (2026.5.10)
**Linux/macOS client polish & two-layer authentication**
- Server identity check (Layer 1): Linux/macOS client verifies server identity with HMAC-SHA256
- Sub-connection auth (Layer 2, TOKEN_CONN_AUTH): every sub-connection's first packet is signed and pinned to its clientID
- Linux client: H.264 hardware encoding, XFixes cursor type detection, UTF-8 protocol capability bit
- macOS client: file manager, remote terminal, clipboard sync, daemon mode
- Master: screen preview thumbnails, region screenshot, remote desktop zoom, Web users filter by group
- Shared code factored into `common/` (rtt_estimator / client_auth_state / posix_net_helpers)
### v1.3.2 (2026.5.1)
**macOS Client & Web Remote Desktop Enhancement**
**macOS client & Web Remote Desktop enhancements**
**New Features:**
- macOS client support: Native macOS client with screen capture, H.264 encoding, keyboard/mouse control, system permission management
- Web remote desktop cursor sync: Real-time display of remote host cursor style in browser
- Trigger functionality: Support custom actions triggered by host online events
- User management: Role-based permission management, multi-user hierarchical control
- DLL execution enhancements: Parameter persistence, auto-run configuration support
- Remote desktop input language switching: Support switching remote host input language
**Improvements:**
- Web remote desktop gesture optimization: Improved two-finger gesture recognition, double-tap drag, Shift key combination support
**Bug Fixes:**
- Fixed Web remote desktop double-click not working for macOS clients
- Fixed macOS Full Disk Access permission detection inaccuracy
- Fixed RestoreMemDLL failure due to incorrect DLL info size
- Fixed multiple DLLs execution failure due to global variable conflict
- Fixed mouse double-click and remote desktop switching issues
- Fixed Linux client build missing libzstd.a
- Brand-new native macOS client: screen capture, H.264 encoding, mouse/keyboard control
- Web remote desktop cursor sync
- Trigger functionality, user management (role-based permissions)
- DLL execution enhancements, remote desktop input-method switching
### v1.3.1 (2026.4.15)
**Web Remote Desktop & Multi-Master Sharing Enhancement**
**Web Remote Desktop (MFC master) & multi-master sharing**
**New Features:**
- Web Remote Desktop: WebSocket-based implementation, access remote desktop via mobile/tablet browser ([Configuration Guide](./docs/WebHTTPS.md))
- Revoke sharing menu: Support revoking clients shared to other masters
- Toolbar audio control: Added system audio toggle icon to remote desktop toolbar
**Improvements:**
- Disable adaptive quality for multi-monitor: Auto-disable when client has multiple monitors
- Status bar auto-refresh expiration date: Immediate refresh after license renewal
- Reduce invalid offline logs: Less logging when client not in host list
- Multi-layer authorization auto-update: Layer-2+ master authorizations sync automatically
- Enhanced usage tips: Added more operation hints for better UX
- DLL cache reuse: Save DLL to registry for reuse on next startup
**Bug Fixes:**
- Fixed keylogger may not work properly while sharing client to other master
- Web remote desktop: WebSocket-based, accessible from phone / tablet browsers
- Multi-monitor: adaptive disabled when multiple monitors are present; expiry date auto-refresh in the status bar
- Multi-layer license auto-update, DLL cache reuse
### v1.3.0 (2026.4.8)
**Multi-Tier FRP Architecture & UI Branding**
**Multi-tier FRP & brand customization**
**New Features:**
- Local FRPS server support (64-bit only): Built-in FRP server for simplified deployment
- Multi-tier architecture automatic FRP integration: Downstream masters auto-acquire upstream FRP config
- V2 authorization downstream connection limit: Control concurrent connections for downstream
- License file import/export support (.lic format)
- Expired authorization renewal support: No need to regenerate license
- Enhanced hardware ID (V2): Fix VPS duplicate SN issue
- MaxDepth control: Limit hierarchical master depth level
- License management enhancements: Quota support, dynamic dialog, delete functionality
- IP geolocation API multi-provider fallback: Improved location success rate
- UI branding customization: Support custom program name, logo, copyright, etc.
- Runtime feature limits: Configurable trial version restrictions
- Input history dropdown: Quick selection of previous inputs
- Client generation new options: More customization settings
- Dynamic project links: Change help/feedback URLs without recompiling
- Local FRPS server, multi-tier auto FRP integration
- V2 license sub-master connection cap, license file import / export
- Enhanced hardware ID (V2), UI brand customization
- Configurable runtime feature limits
**Bug Fixes:**
- Fixed Use-after-free crash in RebuildFilteredIndices
- Fixed IOCP race condition crash in CLock::Lock (#215)
- Fixed crash protection service cleanup and agent elevation issue
- Fixed potential crash from unlimited message log growth
- Fixed UpperHash string length issue after FeatureFlags introduction
- Fixed client SN generation to support HWIDVersion setting
### Earlier versions
**Improvements:**
- Restructured res/ directory with menu icons
- Expired passwords no longer auto-cleared
- Maintain stable connection between downstream and Layer-1 master
### v1.0.2.9 (2026.3.27)
**Network Security & Stability Enhancement**
**New Features:**
- Network configuration dialog: IP whitelist/blacklist management, takes effect immediately
- Configurable rate limiting: DLL request limiting, adjustable IP ban thresholds
- IP history dialog: View license IP login history
- Status bar displays MTBF/runtime and license expiration date
- Agent crash protection: Auto-switch to normal mode after 3 crashes within 5 minutes
- Client search function: Ctrl+F to quickly search IP, location, computer name
- Auto-ban malicious IPs: Auto-ban for 1 hour if >15 connections within 60 seconds
- Proxy Protocol v2 support: Get real client IP behind FRP proxy
- Linux clipboard sync and V2 file transfer support
- Right-click menu to run client program on host
- Multi-layer authorization obfuscation support
**Bug Fixes:**
- Fixed race condition crash in OnUserOfflineMsg
- Fixed FrpcParam lost when client requests FRPC DLL
- Increased max packet size from 10MB to 50MB
- Support mstsc remote session for reading user registry
- Fixed clipboard false trigger when remote desktop minimized
- Fixed master crash when operating process dialog
- Status bar host count updates in real-time
- Reset timeval before each select() call on Linux
- Passcode format validation to filter garbage data
**Improvements:**
- Enhanced authorization check with IP ban notifications
- Support master program running with user privilege
- Large DLL auto-fallback to TinyRun
### v1.2.8 (2026.3.11)
**Email Notification & Remote Audio**
- Host online email notification (SMTP config, keyword matching, right-click quick add)
- Remote audio playback (WASAPI Loopback) + Opus compression (24:1)
- Multiple FRPS servers simultaneous connection support
- Custom cursor display and tracking
- V2 authorization protocol (ECDSA signature)
- Fixed garbled text on non-Chinese Windows systems
- Linux client screen compression algorithm optimization
### v1.2.7 (2026.2.28)
**V2 File Transfer Protocol**
- Support C2C (client-to-client) direct transfer
- Resumable transfer and large file support (>4GB)
- SHA-256 file integrity verification
- WebView2 + xterm.js modern terminal
- Linux file management support
- Host list batch update optimization, reduced UI flickering
### v1.2.6 (2026.2.16)
**Remote Desktop Toolbar Rewrite**
- Status window showing RTT, FPS, resolution
- Fullscreen toolbar supports 4 positions and multi-monitor
- H.264 bandwidth optimization
- License management UI improvements
### v1.2.5 (2026.2.11)
**Adaptive Quality Control & Linux Client**
- RTT-based intelligent quality adjustment
- RGB565 algorithm (50% bandwidth savings)
- Scroll detection optimization (50-80% bandwidth savings)
- Linux client initial release
For complete update history, see: [history.md](./history.md)
The v1.2.x series (email notifications, remote audio via Opus, V2 license protocol, V2 file transfer, modern Web terminal with xterm.js, remote desktop toolbar rewrite, adaptive quality control, first Linux client, …) and the full evolution since 2019 are documented in [history.md](./history.md).
---
## Related Projects
- [HoldingHands](https://github.com/yuanyuanxiang/HoldingHands) - Full English interface remote control
- [Gh0st](https://github.com/yuanyuanxiang/Gh0st) - Classic Gh0st implementation
- [HoldingHands](https://github.com/yuanyuanxiang/HoldingHands) — English-only remote control
- [Gh0st](https://github.com/yuanyuanxiang/Gh0st) — Classic Gh0st implementation
---
## Contact
| Channel | Link |
|---------|------|
|---|---|
| **QQ** | 962914132 |
| **Telegram** | [@doge_grandfather](https://t.me/doge_grandfather) |
| **Email** | [yuanyuanxiang163@gmail.com](mailto:yuanyuanxiang163@gmail.com) |
| **Issues** | [Report Issues](https://t.me/SimpleRemoter) |
| **Issues** | [Report a bug](https://t.me/SimpleRemoter) |
| **PR** | [Contribute](https://git.simpleremoter.com/) |
### Sponsorship
### Sponsor
This project originated from technical learning and personal interest. The author will update irregularly based on spare time. If this project has been helpful to you, please consider sponsoring:
This project is a side-of-the-desk effort driven by technical curiosity. The author updates it in spare time. If it helps you, sponsorship is welcome:
[![Sponsor](https://img.shields.io/badge/Sponsor-Support%20This%20Project-ff69b4?style=for-the-badge)](https://github.com/yuanyuanxiang/yuanyuanxiang/blob/main/images/QR_Codes.jpg)