# SimpleRemoter
**[简体中文](./ReadMe.md) | [繁體中文](./ReadMe_TW.md) | [English](./ReadMe_EN.md)**
---
> [!WARNING]
> **Important Legal Notice**
>
> 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.
---
## Table of Contents
- [Overview](#overview)
- [What's New: Full-Platform Loop Closed](#whats-new-full-platform-loop-closed)
- [Compliance & Anti-Abuse](#compliance--anti-abuse)
- [Features](#features)
- [Cross-Platform Support](#cross-platform-support)
- [Architecture](#architecture)
- [Getting Started](#getting-started)
- [User Documentation](#user-documentation)
- [Changelog](#changelog)
- [Related Projects](#related-projects)
- [Contact](#contact)
---
## Overview
**SimpleRemoter** is an end-to-end cross-platform remote control solution.
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.
**Original source:** [zibility/Remote](https://github.com/zibility/Remote) | **Started:** 2019.1.1
[](https://star-history.com/#yuanyuanxiang/SimpleRemoter&Date)
---
## What's New: Full-Platform Loop Closed
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.
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.
### Which Master Should You Use
| 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 |
> [!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.
### Go Master Capabilities (v1.3.4)
- **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]
> **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).
---
## Features
### Remote Desktop
- **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))
### File Management
- **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
- **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
| 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 |
---
## Cross-Platform Support
### Windows Client
**Requirements**: Windows 7 SP1 or later
**Feature completeness**: ✅ All features supported
### Linux Client (v1.2.5+)
**Requirements**:
- Display server: X11/Xorg (Wayland not yet supported)
- Required: libX11. Recommended: libXtst (XTest extension), libXss (idle detection)
| 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 |
**Build**: `cd linux && cmake . && make`
### macOS Client (v1.3.2+)
**Requirements**:
- macOS 10.15 (Catalina) or later
- Architecture: Intel (x64) and Apple Silicon (arm64) universal binary
- Permissions: Screen Recording, Accessibility, Full Disk Access
| 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 |
**Build**: `cd macos && ./build.sh`
### Go Master (v1.3.4+)
**Requirements**: Go 1.21+ (build time only); binary runs without dependencies
| 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` |
**Build**: `cd server/go && go build -o server_linux_amd64 ./cmd`
---
## Architecture
### Cross-Platform Topology
```
┌────────────────────────────────────────────────────────┐
│ 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) │
└─────────┘ └─────────┘ └─────────┘
```
### Multi-Layer Authorization (simplified view)
```
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
```
| 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)) |
Full description: [Multi-Layer License](./docs/MultiLayerLicense.md)
---
## Getting Started
### 5-Minute Walkthrough
No compilation required — download and run:
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 the first test, run both the master and the client on the same machine using `127.0.0.1` as the server address.
### Go Master Deployment (VPS)
See the [Web Remote Desktop config](./docs/WebHTTPS.md). The minimum recipe:
```bash
# 1. Run the Go master on the VPS
nohup ./server_linux_amd64 --port 6543 --http-port 9001 > yama.log 2>&1 &
# 2. nginx reverse proxy: 9001 → HTTPS
# See docs/WebHTTPS.md
# 3. Open https://yourdomain.com/ in a browser, log in, add clients
```
### Trial License (v1.2.4+)
A trial credential is provided — 2-year validity, 20 concurrent connections, LAN-only:
```
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**
>
> 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`
---
## User Documentation
| 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.4 (2026.5.20)
**Go master & full-platform master loop & Linux/macOS clipboard**
**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:**
- 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:**
- 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 enhancements**
- 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 (MFC master) & multi-master sharing**
- 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 & brand customization**
- 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
### Earlier versions
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) — 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 a bug](https://t.me/SimpleRemoter) |
| **PR** | [Contribute](https://git.simpleremoter.com/) |
### Sponsor
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:
[](https://github.com/yuanyuanxiang/yuanyuanxiang/blob/main/images/QR_Codes.jpg)
---
If you like this project, please give it a ⭐ Star!