macOS Remote Desktop Client
===========================
Prerequisites:
1. Xcode Command Line Tools: xcode-select --install
2. CMake: brew install cmake
3. OpenSSL (TLS transport): brew install openssl@3
CMake 自动探测 /opt/homebrew/opt/openssl@3,也可用
cmake .. -DOPENSSL_ROOT_DIR=/path/to/openssl 指定。
构建目标是 Apple Silicon (arm64) 单架构:Homebrew 的 OpenSSL 只有本机架构,
保留 x86_64 slice 会链接失败。Intel Mac 需另建 x86_64 的 OpenSSL 单独构建。
Build:
chmod +x build.sh
./build.sh
Or manually:
mkdir build && cd build
cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0
make
Run:
./build/bin/ghost
Configuration:
Server address is configured in main.mm (g_SETTINGS variable).
Modify before building if needed.
TLS Transport:
Default is plaintext on first connect. The controller's host right-click menu
("TLS 传输") sends the trust anchor; the client stores it at
~/.config/ghost/yama-ca.pem, hot-reloads and reconnects over TLS 1.2
(fail-closed, pinned to that anchor). "取消TLS" deletes the file and
reconnects in plaintext. Existing sessions survive only if the transport does
not change (replacing the certificate keeps TLS).
Verify after building:
otool -L build/bin/ghost | grep -i ssl # 期望无输出:OpenSSL 已静态链接
tail -f /tmp/ghost.log
Startup prints one of:
[TLS] transport on first connect: plaintext (no trust anchor)
[TLS] transport on first connect: TLS (trust anchor present)
Clicking "TLS 传输" should log "TLS transport switched to TLS, reconnecting";
the host's TLS column in the online list then shows Y. "取消TLS" logs
"switched to plaintext" and the column flips back to N.
If the log says "trust anchor exists but failed to load", the client refuses
to connect (fail-closed) until the anchor is fixed or removed.
Client Log:
The controller's host right-click menu ("运行日志") sends COMMAND_QUERY_LOG;
the client opens a sub-connection and reports its in-memory log ring
(Logger, last 1000 lines) as TOKEN_REPORT_LOG. On macOS Mprintf (as defined
by common/logger.h) writes that ring, and Logger mirrors the same line to
stderr, so one Mprintf line reads identically in the dialog and in
/tmp/ghost.log (same prefix and timestamp); content older than the
1000-entry ring exists only in the file. main.mm logs startup, config,
permissions, TLS, WS, connection and exit through Mprintf, so those lines
are all visible in the dialog. The ObjC helper modules (ScreenHandler /
H264Encoder / InputHandler / Permissions) still use NSLog, and the two
"=== ghost ... started ===" banners are raw write(2) calls; all of those
appear only in /tmp/ghost.log. Mprintf lines also no longer go to Apple's
Unified Logging (NSLog in the helpers still does). The MCP tool
get_client_log reads that same ring.
Verify: open "运行日志" for the Mac host; the dialog should show startup
lines such as "=== macOS Ghost Client ===", "Config loaded from ...",
the permission results, "[TLS] transport on first connect: ...", plus
command and heartbeat entries.
Note: the POSIX client reports a snapshot once per connection (the Windows
client keeps pushing increments every 3s). Closing and reopening "运行日志"
takes a fresh snapshot.
Permissions Required:
1. Screen Recording - System Settings > Privacy & Security > Screen Recording
2. Accessibility - System Settings > Privacy & Security > Accessibility
Features:
[x] Screen capture (CGDisplayCreateImage)
[x] H264 video encoding (VideoToolbox)
[x] Mouse control (move, click, drag, scroll)
[x] Keyboard control (full VK code mapping)
[x] Retina display support (coordinate scaling)
[x] Network connection (IOCPClient)
[x] LOGIN_INFOR (system info reporting)
[x] Heartbeat with RTT estimation
[x] Active window tracking
[x] Quality level adjustment (FPS/algorithm)
Files:
CMakeLists.txt - Build configuration
Permissions.h/mm - macOS permission handling
ScreenHandler.h/mm - Screen capture and H264 encoding
InputHandler.h/mm - Mouse/keyboard simulation
H264Encoder.h/mm - VideoToolbox H264 encoder
SystemManager.h/mm - Process management
main.mm - Entry point, LOGIN_INFOR, heartbeat
Quality Levels:
Level 0: 5 FPS, Grayscale (emergency low bandwidth)
Level 1: 10 FPS, RGB565
Level 2: 15 FPS, H264 (default, office work)
Level 3: 20 FPS, H264
Level 4: 25 FPS, H264
Level 5: 30 FPS, H264 (smooth)
Notes:
- First frame is always raw bitmap (TOKEN_FIRSTSCREEN)
- Subsequent frames use H264 encoding (TOKEN_NEXTSCREEN)
- Coordinates are scaled for Retina displays automatically
- Windows VK codes are mapped to macOS key codes