docs: Add comprehensive project documentation from claude-projects scan
Added: - PROJECTS_INDEX.md - Master catalog of 7 active projects - GURURMM_API_ACCESS.md - Complete API documentation and credentials - clients/dataforth/dos-test-machines/README.md - DOS update system docs - clients/grabb-durando/website-migration/README.md - Migration procedures - clients/internal-infrastructure/ix-server-issues-2026-01-13.md - Server issues - projects/msp-tools/guru-connect/README.md - Remote desktop architecture - projects/msp-tools/toolkit/README.md - MSP PowerShell tools - projects/internal/acg-website-2025/README.md - Website rebuild docs - test_gururmm_api.py - GuruRMM API testing script Modified: - credentials.md - Added GuruRMM database and API credentials - GuruRMM agent integration files (WebSocket transport) Total: 38,000+ words of comprehensive project documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
599
projects/msp-tools/guru-connect/README.md
Normal file
599
projects/msp-tools/guru-connect/README.md
Normal file
@@ -0,0 +1,599 @@
|
||||
# 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
|
||||
- [x] Project structure and build system
|
||||
- [x] Protocol Buffers definitions
|
||||
- [x] Basic WebSocket relay server
|
||||
- [x] 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)
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# macOS
|
||||
brew install protobuf
|
||||
|
||||
# Windows (via Chocolatey)
|
||||
choco install protoc
|
||||
|
||||
# Linux
|
||||
apt-get install protobuf-compiler
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```powershell
|
||||
# Run from Windows
|
||||
.\target\release\guruconnect-agent.exe
|
||||
|
||||
# With custom server URL
|
||||
.\target\release\guruconnect-agent.exe --server wss://guruconnect.azcomputerguru.com
|
||||
```
|
||||
|
||||
### Dashboard
|
||||
|
||||
```bash
|
||||
cd dashboard
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Server Config
|
||||
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
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)
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```sql
|
||||
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
|
||||
|
||||
```bash
|
||||
# Run all unit tests
|
||||
cargo test
|
||||
|
||||
# Test specific module
|
||||
cargo test --package guruconnect-agent --lib capture
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```powershell
|
||||
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:**
|
||||
```powershell
|
||||
# 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:
|
||||
|
||||
```jsx
|
||||
// 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:**
|
||||
```http
|
||||
POST /api/sessions/start
|
||||
Authorization: Bearer <jwt-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"machine_id": "abc-123-def",
|
||||
"quality": "medium"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user