claudetools/projects/msp-tools/guru-connect

GuruConnect - Remote Desktop Solution

Project Type: Internal Tool / MSP Platform Component Status: Phase 1 MVP Development Technology Stack: Rust, React, WebSockets, Protocol Buffers Integration: GuruRMM platform

Project Overview

GuruConnect is a remote desktop solution similar to ScreenConnect/ConnectWise Control, designed for fast, secure remote screen control and backstage tools for Windows systems. Built as an integrated component of the GuruRMM platform.

Goal: Provide MSP technicians with enterprise-grade remote desktop capabilities fully integrated with GuruRMM's monitoring and management features.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      GuruConnect System                       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Dashboard     │         │  GuruConnect    │         │  GuruConnect    │
│   (React)       │◄──WSS──►│  Server (Rust)  │◄──WSS──►│  Agent (Rust)   │
│                 │         │                 │         │                 │
│  - Session list │         │  - Relay frames │         │  - Capture      │
│  - Live viewer  │         │  - Auth/JWT     │         │  - Input inject │
│  - Controls     │         │  - Session mgmt │         │  - Encoding     │
└─────────────────┘         └─────────────────┘         └─────────────────┘
                                    │
                                    │
                                    ▼
                            ┌─────────────────┐
                            │   PostgreSQL    │
                            │   (Sessions,    │
                            │    Audit Log)   │
                            └─────────────────┘

Components

1. Agent (Rust - Windows)

Location: ~/claude-projects/guru-connect/agent/

Runs on Windows client machines to capture screen and inject input.

Responsibilities:

• Screen capture via DXGI (with GDI fallback)
• Frame encoding (Raw+Zstd, VP9, H264)
• Dirty rectangle detection
• Mouse/keyboard input injection
• WebSocket client connection to server

2. Server (Rust + Axum)

Location: ~/claude-projects/guru-connect/server/

Relay server that brokers connections between dashboard and agents.

Responsibilities:

• WebSocket relay for screen frames and input
• JWT authentication for dashboard users
• API key authentication for agents
• Session management and tracking
• Audit logging
• Database persistence

3. Dashboard (React)

Location: ~/claude-projects/guru-connect/dashboard/

Web-based viewer interface, to be integrated into GuruRMM dashboard.

Responsibilities:

• Live video stream display
• Mouse/keyboard event capture
• Session controls (pause, record, etc.)
• Quality/encoding settings
• Connection status

4. Protocol Definitions (Protobuf)

Location: ~/claude-projects/guru-connect/proto/

Shared message definitions for efficient serialization.

Key Message Types:

• VideoFrame - Screen frames (raw+zstd, VP9, H264)
• MouseEvent - Mouse input (click, move, scroll)
• KeyEvent - Keyboard input
• SessionRequest/Response - Session management

---

Encoding Strategy

GuruConnect dynamically selects encoding based on network conditions and GPU availability:

Scenario	Encoding	Target	Notes
LAN (<20ms RTT)	Raw BGRA + Zstd	<50ms latency	Dirty rectangles only
WAN + GPU	H264 hardware	100-500 Kbps	NVENC/QuickSync
WAN - GPU	VP9 software	200-800 Kbps	CPU encoding

Implementation Details

DXGI Screen Capture:

• Desktop Duplication API for Windows 8+
• Dirty region tracking (only changed areas)
• Fallback to GDI BitBlt for Windows 7

Compression:

• Zstd for lossless (LAN scenarios)
• VP9 for high-quality software encoding
• H264 for GPU-accelerated encoding

Frame Rate Adaptation:

• Target 30 FPS for active sessions
• Drop to 5 FPS when idle
• Skip frames if network buffer full

---

Security Model

Authentication

Dashboard Users: JWT tokens

• Login via GuruRMM credentials
• Tokens expire after 24 hours
• Refresh tokens for long sessions

Agents: API keys

• Pre-registered API key per agent
• Tied to machine ID in GuruRMM database
• Rotatable via admin panel

Transport Security

TLS Required: All WebSocket connections use WSS (TLS)

• Certificate validation enforced
• Self-signed certs rejected in production
• SNI support for multi-tenant hosting

Session Audit

Logged Events:

• Session start/end with user and machine IDs
• Connection duration and data transfer
• User actions (mouse clicks, keystrokes - aggregate only)
• Quality/encoding changes
• Recording start/stop (Phase 4)

Retention: 90 days in PostgreSQL

---

Phase 1 MVP Goals

Completed Features

• Project structure and build system
• Protocol Buffers definitions
• Basic WebSocket relay server
• DXGI screen capture implementation

In Progress

• GDI fallback for screen capture
• Raw + Zstd encoding with dirty rectangles
• Mouse and keyboard input injection
• React viewer component
• Session management API

Future Phases

• Phase 2: VP9 and H264 encoding
• Phase 3: GuruRMM dashboard integration
• Phase 4: Session recording and playback
• Phase 5: File transfer and clipboard sync
• Phase 6: Multi-monitor support

---

Development

Prerequisites

Rust: 1.75+ (install via rustup)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows SDK: For agent development

• Visual Studio 2019+ with C++ tools
• Windows 10 SDK

Protocol Buffers Compiler:

# macOS
brew install protobuf

# Windows (via Chocolatey)
choco install protoc

# Linux
apt-get install protobuf-compiler

Build Commands

# Build all components (from workspace root)
cd ~/claude-projects/guru-connect
cargo build --release

# Build agent only
cargo build -p guruconnect-agent --release

# Build server only
cargo build -p guruconnect-server --release

# Run tests
cargo test

# Check for warnings
cargo clippy

Cross-Compilation

Building Windows agent from Linux:

# Install Windows target
rustup target add x86_64-pc-windows-msvc

# Build (requires cross or appropriate linker)
cross build -p guruconnect-agent --target x86_64-pc-windows-msvc --release

# Alternative: Use GitHub Actions for Windows builds

---

Running in Development

Server

# Development mode
cargo run -p guruconnect-server

# With environment variables
export DATABASE_URL=postgres://user:pass@localhost/guruconnect
export JWT_SECRET=your-secret-key-here
export RUST_LOG=debug
cargo run -p guruconnect-server

# Production build
./target/release/guruconnect-server --bind 0.0.0.0:8443

Agent

Agent must run on Windows:

# Run from Windows
.\target\release\guruconnect-agent.exe

# With custom server URL
.\target\release\guruconnect-agent.exe --server wss://guruconnect.azcomputerguru.com

Dashboard

cd dashboard
npm install
npm run dev

# Production build
npm run build

---

Configuration

Server Config

Environment Variables:

DATABASE_URL=postgres://guruconnect:password@localhost:5432/guruconnect
JWT_SECRET=<generate-random-256-bit-secret>
BIND_ADDRESS=0.0.0.0:8443
TLS_CERT=/path/to/cert.pem
TLS_KEY=/path/to/key.pem
LOG_LEVEL=info

Agent Config

Command-Line Flags:

--server <url>           Server WebSocket URL (wss://...)
--api-key <key>          Agent API key for authentication
--quality <low|med|high> Default quality preset
--log-level <level>      Logging verbosity

Registry Settings (Windows):

HKLM\SOFTWARE\GuruConnect\Server = wss://guruconnect.azcomputerguru.com
HKLM\SOFTWARE\GuruConnect\ApiKey = <api-key>

---

Deployment

Server Deployment

Recommended: Docker container on GuruRMM server (172.16.3.30)

# docker-compose.yml
version: '3.8'
services:
  guruconnect:
    image: guruconnect-server:latest
    ports:
      - "8443:8443"
    environment:
      DATABASE_URL: postgres://guruconnect:${DB_PASS}@db:5432/guruconnect
      JWT_SECRET: ${JWT_SECRET}
    volumes:
      - ./certs:/certs:ro
    depends_on:
      - db

Agent Deployment

Method 1: GuruRMM Agent Integration

• Bundle with GuruRMM agent installer
• Auto-start via Windows service
• Managed API key provisioning

Method 2: Standalone MSI Installer

• Separate install package
• Manual API key configuration
• Service registration

---

Monitoring and Logs

Server Logs

# View real-time logs
docker logs -f guruconnect-server

# Check error rate
grep ERROR /var/log/guruconnect/server.log | wc -l

Agent Logs

Location: C:\ProgramData\GuruConnect\Logs\agent.log

Key Metrics:

• Frame capture rate
• Encoding latency
• Network send buffer usage
• Connection errors

Session Metrics

Database Query:

SELECT
    machine_id,
    user_id,
    AVG(duration_seconds) as avg_duration,
    SUM(bytes_transferred) as total_data
FROM sessions
WHERE created_at > NOW() - INTERVAL '7 days'
GROUP BY machine_id, user_id;

---

Testing

Unit Tests

# Run all unit tests
cargo test

# Test specific module
cargo test --package guruconnect-agent --lib capture

Integration Tests

# Start test server
cargo run -p guruconnect-server -- --bind 127.0.0.1:8444

# Run agent against test server
cargo run -p guruconnect-agent -- --server ws://127.0.0.1:8444

# Dashboard tests
cd dashboard && npm test

Performance Testing

# Measure frame capture latency
cargo bench --package guruconnect-agent

# Network throughput test
iperf3 -c <server> -p 8443

---

Troubleshooting

Agent Cannot Connect

Check:

1. Server URL correct? wss://guruconnect.azcomputerguru.com
2. API key valid? Check GuruRMM admin panel
3. Firewall blocking? Test: telnet <server> 8443
4. TLS certificate valid? Check browser: https://<server>:8443/health

Logs:

Get-Content C:\ProgramData\GuruConnect\Logs\agent.log -Tail 50

Black Screen in Viewer

Common Causes:

1. DXGI capture failed, no GDI fallback
2. Encoding errors (check agent logs)
3. Network packet loss (check quality)
4. Agent service stopped

Debug:

# Check agent service
Get-Service GuruConnectAgent

# Test screen capture manually
.\guruconnect-agent.exe --test-capture

High CPU Usage

Possible Issues:

1. Software encoding (VP9) on weak CPU
2. Full-screen capture when dirty rects should be used
3. Too high frame rate for network conditions

Solutions:

• Enable H264 hardware encoding (if GPU available)
• Lower quality preset
• Reduce frame rate to 15 FPS

---

Key References

RustDesk Source: ~/claude-projects/reference/rustdesk/

GuruRMM: ~/claude-projects/gururmm/ and D:\ClaudeTools\projects\msp-tools\guru-rmm\

Development Plan: ~/.claude/plans/shimmering-wandering-crane.md

Session Logs: ~/claude-projects/session-logs/2025-12-21-guruconnect-session.md

---

Integration with GuruRMM

Dashboard Integration

GuruConnect viewer will be embedded in GuruRMM dashboard:

// Example React component integration
import { GuruConnectViewer } from '@guruconnect/react';

function MachineDetails({ machineId }) {
  return (
    <div>
      <h2>Machine: {machineId}</h2>
      <GuruConnectViewer
        machineId={machineId}
        apiToken={userToken}
      />
    </div>
  );
}

API Integration

Start Session:

POST /api/sessions/start
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "machine_id": "abc-123-def",
  "quality": "medium"
}

Response:

{
  "session_id": "sess_xyz789",
  "websocket_url": "wss://guruconnect.azcomputerguru.com/ws/sess_xyz789"
}

---

Roadmap

Phase 1: MVP (In Progress)

• Basic screen capture and viewing
• Mouse/keyboard input
• Simple quality control

Phase 2: Production Ready

• VP9 and H264 encoding
• Adaptive quality
• Connection recovery
• Performance optimization

Phase 3: GuruRMM Integration

• Embedded dashboard viewer
• Single sign-on
• Unified session management
• Audit integration

Phase 4: Advanced Features

• Session recording and playback
• Multi-monitor support
• Audio streaming
• Clipboard sync

Phase 5: Enterprise Features

• Permission management
• Session sharing (invite technician)
• Chat overlay
• File transfer

---

Project History

2025-12-21: Initial project planning and architecture design 2025-12-21: Build system setup, basic agent structure 2026-01-XX: Phase 1 MVP development ongoing

---

License & Credits

License: Proprietary (Arizona Computer Guru internal use)

Credits:

• Architecture inspired by RustDesk
• Built with Rust, Tokio, Axum
• WebRTC considered but rejected (complexity)

---

Support

Technical Contact: Mike Swanson Email: mike@azcomputerguru.com Phone: 520.304.8300

---

Status: Active Development - Phase 1 MVP Priority: Medium (supporting GuruRMM platform) Next Milestone: Complete dirty rectangle detection and input injection