Overview
This is the implementation guide for the custom canvas-based remote desktop viewer for MeshCentral. This replaces the broken iframe approach with a native WebSocket connection.
Status: Phase 2 - Infrastructure Complete, Requires Real Agent Testing
Architecture
┌─────────────────────┐ Direct WebSocket ┌──────────────────────┐
│ Canvas Viewer │◀─────────────────────────────────▶│ MeshCentral Fork │
│ (React Frontend) │ wss://meshcentral/api/canvas... │ (Custom Endpoint) │
└─────────────────────┘ └──────────────────────┘
│
Desktop Multiplexor
│
▼
┌──────────────────┐
│ Agent on Device │
└──────────────────┘
Implementation Phases
✅ Phase 1: Endpoint + Authentication (COMPLETE)
Status: Fully implemented and tested
What's Working:
- Custom WebSocket endpoint: /api/canvas-desktop/:nodeId
- JWT token validation using existing auth module
- Test mode bypass with CANVAS_TEST_MODE=true environment variable
- Connection establishment and ping/pong testing
- URL encoding for node IDs with special characters (e.g., node//test-123)
- Error handling and comprehensive logging
✅ Phase 2: Screen Streaming Infrastructure (COMPLETE)
Status: Infrastructure complete, requires real agent for testing
What's Working:
- Desktop multiplexor integration via CreateDesktopMultiplexor
- WebSocket message handling for screen data
- TrafficStats initialization for accounting
- Peer management (viewer/agent relationship)
- Socket resume/pause handling
- Connection lifecycle management
What's Blocked:
- Actual screen streaming requires a real agent connected to MeshCentral
- Test node IDs (e.g., node//test-123) don't exist in the database
- Desktop multiplexor needs valid node records with mesh associations
Critical Fixes Applied:
- ✅ URL encoding for node IDs containing "//" characters
- ✅ Correct desktop multiplexor object references (obj.desktoprelays)
- ✅ Export of CreateDesktopMultiplexor function from module
- ✅ Initialize trafficStats.desktopMultiplex before use
- ✅ Socket resume before sending messages
⏳ Phase 3: Mouse/Keyboard Input (PLANNED)
Status: Not yet started
What's NOT Working Yet:
- Mouse movement and click forwarding
- Keyboard input and special key handling
- Quality/compression controls (Phase 4)
- Clipboard synchronization (Phase 4)
Testing
Test with Mock Node (Infrastructure Validation)
cd /home/cw/Documents/IBG_HUB/rmm-psa-meshcentral
node test-phase2-detailed.js "test-token" "node//test-123"
Expected Output (Infrastructure Working):
✅ WebSocket connection OPENED
📨 Message: {"type":"test","message":"Immediate send test"}
📨 Message: {"type":"connected","phase":2,"capabilities":["ping","auth","screen","input"]}
📨 Message: {"type":"error","message":"Failed to establish desktop session"}
Note: The "Failed to establish desktop session" error is expected for test node IDs because they don't exist in the database. This confirms the infrastructure is working correctly.
Test with Real Agent (Full Functionality)
Requirements:
- Have the RMM agent installed on a test device
- Agent must be connected to MeshCentral (visible in dashboard)
- Get the real node ID from the backend API or MeshCentral console
✅ WebSocket connection OPENED
📤 Sending ping...
📨 Message 1 received: {
"type": "connected",
"nodeId": "node//...",
"userId": "user//...",
"tenantId": "...",
"message": "Canvas desktop endpoint connected (Phase 1 - Testing)",
"phase": 1,
"capabilities": ["ping", "auth"]
}
🎉 Connection Successful!
📨 Message 2 received: {
"type": "pong",
"timestamp": 1709539200000,
"server": "meshcentral"
}
⚡ Latency: 45ms
📋 Phase 2: Screen Streaming + Input (NEXT)
Timeline: Week 2
Tasks:
- Connect custom endpoint to agent desktop stream
- Forward screen frames to WebSocket client
- Implement mouse event handling
- Implement keyboard event handling
- Build minimal React canvas component
- Test end-to-end screen updates
Files to Modify:
🎨 Phase 3: Advanced Features
Timeline: Week 3
Tasks:
- Quality controls (JPEG quality, framerate)
- Delta frame encoding
- Clipboard synchronization
- File transfer
- Fullscreen mode
- Mobile touch support
- Bandwidth monitoring
🚀 Phase 4: Production
Timeline: Week 4
Tasks:
- Performance optimization
- Cross-browser testing
- Load testing
- Security audit
- Documentation
- Production deployment
Files Modified
Phase 1 (Current)
rmm-psa-meshcentral/meshcentral-fork/webserver.js
- Added custom endpoint at line ~7154
- Handles WebSocket connections with JWT auth
- Sends ping/pong for testing
- ~100 lines of new code
rmm-psa-meshcentral/test-canvas-endpoint.js
- Test script for WebSocket connection
- Validates JWT authentication works
- Measures latency
- ~200 lines
rmm-psa-docs/MESHCENTRAL_REDESIGN_SPEC.md
- Complete technical specification
- Updated with fork advantage
- Implementation timeline
Local Testing
1. Get Required Values
JWT Token (from dashboard):
// In browser console on dashboard:
localStorage.getItem('token')
Node ID (from MeshCentral or backend API):
# Via backend API:
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
https://rmm-psa-backend-t9f7k.ondigitalocean.app/api/agents
# Look for "meshcentral_nodeid" field
2. Run Test Script
cd /home/cw/Documents/IBG_HUB/rmm-psa-meshcentral
# Install dependencies if needed
npm install ws
# Run test
node test-canvas-endpoint.js \
"eyJhbGciOiJIUzI1NiIs..." \
"node//abc123..." \
"wss://rmm-psa-meshcentral-aq48h.ondigitalocean.app"
3. Verify Success
Look for:
- ✅ "WebSocket connection OPENED"
- ✅ "Connection Successful!"
- ✅ Pong responses with latency
- ✅ No authentication errors
Deployment
To Staging
cd /home/cw/Documents/IBG_HUB/rmm-psa-meshcentral
# Commit changes
git add meshcentral-fork/webserver.js test-canvas-endpoint.js
git commit -m "Add Phase 1 canvas desktop endpoint
- Custom WebSocket endpoint at /api/canvas-desktop/:nodeId
- JWT authentication using existing auth module
- Ping/pong for connection testing
- Comprehensive logging and error handling
Phase 1: Endpoint + Auth ✅
Phase 2: Screen streaming (next)"
git push origin main
# Trigger deployment to DigitalOcean
doctl apps create-deployment $(doctl apps list | grep meshcentral | awk '{print $1}')
To Production
Prerequisites:
- All phases completed
- Load testing passed
- Security audit passed
- Documentation complete
# Deploy to production (after all phases complete)
doctl apps create-deployment <production-app-id>
Troubleshooting
Connection Refused
❌ WebSocket ERROR: ECONNREFUSED
Solution: MeshCentral not running or wrong URL
- Check: doctl apps list | grep meshcentral
- Verify URL matches deployed instance
Authentication Failed
📨 Message: { "type": "error", "message": "Authentication failed" }
Solution: Invalid or expired JWT token
- Get fresh token from dashboard
- Verify JWT_SECRET matches between backend and MeshCentral
- Check token expiration: jwt.io (paste token)
Node Not Found
📨 Message: { "type": "error", "message": "Node not found" }
Solution: Invalid node ID or wrong tenant
- Verify node ID format: node// prefix
- Check tenant access to node
- List available nodes: GET /api/agents
WebSocket Upgrade Failed
❌ WebSocket ERROR: Unexpected server response: 404
Solution: Endpoint not deployed
- Verify changes are pushed: git log --oneline -1
- Check deployment status: doctl apps get <app-id>
- Wait for build to complete (~3-5 minutes)
Next Steps
For Phase 2 (Week 2)
- Study Agent Connection:
// In meshdesktopmultiplex.js
obj.agent = <agent connection>
obj.viewers = [<viewer connections>]
- Hook Into Desktop Stream:
// In webserver.js, canvas endpoint:
// Connect to CreateDesktopMultiplexor
// Subscribe to screen frame events
// Forward to canvas WebSocket
- Create React Component:
// src/components/RemoteDesktop/CanvasViewer.jsx
<canvas ref={canvasRef} />
// Connect to wss://meshcentral/api/canvas-desktop/:nodeId
// Render screen frames
- Test End-to-End:
- Frontend connects
- Screen renders on canvas
- Mouse moves on screen
- Keyboard input works
Resources
Support
For issues or questions:
- Check logs: doctl apps logs <app-id> --type=run
- Review technical spec
- Test with test-canvas-endpoint.js
- Check authentication state
Last Updated: 2026-03-04
Current Phase: Phase 1 - Testing ✅
Next Phase: Phase 2 - Screen Streaming 📋
1.14.0