Remote Desktop

Setup

On first use, read setup.md for integration guidelines and help the user with their question.

When to Use

User needs remote desktop access to another machine. Agent handles protocol selection, connection commands, tunnel setup, and troubleshooting display issues.

Architecture

Config lives in ~/remote-desktop/. See memory-template.md for structure.

~/remote-desktop/
├── memory.md         # Saved hosts, preferences
└── hosts/            # Per-host connection profiles

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md
Protocol details	protocols.md
Troubleshooting	troubleshooting.md

Core Rules

1. Protocol Selection

Target OS	Best Protocol	Why
Windows	RDP	Native, best performance
Linux (desktop)	VNC or X11	VNC for persistent, X11 for apps
macOS	VNC (built-in)	Screen Sharing uses VNC
Headless Linux	SSH + X11 forwarding	No desktop needed

2. Security First

• Always prefer SSH tunneling over direct exposure
• Never expose RDP (3389) or VNC (5900) to internet directly
• Use SSH keys, not passwords
• If direct needed, use VPN or firewall rules

3. Connection Commands

RDP to Windows:

# xfreerdp (recommended)
xfreerdp /v:HOST /u:USER /p:PASS /size:1920x1080 /dynamic-resolution

# With SSH tunnel first
ssh -L 3389:localhost:3389 user@jumphost
xfreerdp /v:localhost /u:USER

VNC:

# Direct (NOT recommended for internet)
vncviewer HOST:5901

# Via SSH tunnel (recommended)
ssh -L 5901:localhost:5901 user@HOST
vncviewer localhost:5901

SSH X11 forwarding:

# Single app
ssh -X user@HOST firefox

# Trusted (faster, less secure)
ssh -Y user@HOST

4. Port Defaults

Protocol	Default Port	Display :0	Display :1
RDP	3389	3389	-
VNC	5900	5900	5901
SSH	22	-	-
NoMachine	4000	4000	-

5. Tunnel Everything

For any remote desktop over internet:

# Local port forward
ssh -L LOCAL_PORT:TARGET:REMOTE_PORT user@JUMPHOST

# Example: RDP via jumphost
ssh -L 13389:windows-pc:3389 user@jumphost
xfreerdp /v:localhost:13389 /u:USER

6. Clipboard and Files

Tool	Clipboard	File Transfer
xfreerdp	/clipboard flag	/drive:share,/path
vncviewer	Usually works	Separate SCP/SFTP
SSH X11	Needs xclip setup	SCP/SFTP

7. Save Working Configs (with consent)

When a connection works, ask "Want me to save this config for next time?" If yes, save to ~/remote-desktop/hosts/:

# hostname.md
host: 192.168.1.50
protocol: rdp
user: admin
tunnel: ssh user@jumphost -L 3389:192.168.1.50:3389
resolution: 1920x1080
notes: Windows 11 dev machine

Never save passwords — only hostnames, users, and connection flags.

Common Traps

• Black screen after VNC connect → Display manager not running or wrong display number. Try :1 instead of :0, or start a VNC server: vncserver :1
• RDP disconnects immediately → Check Network Level Authentication (NLA) settings, or add /sec:tls to xfreerdp
• X11 forwarding not working → Ensure X11Forwarding yes in server's /etc/ssh/sshd_config and ForwardX11 yes in client config
• Slow VNC performance → Use tighter encodings: vncviewer -encoding tight HOST:1
• "Connection refused" → Service not running, firewall blocking, or wrong port. Check with ss -tlnp | grep PORT
• Clipboard not syncing → xfreerdp needs /clipboard, VNC needs vncconfig running

Security & Privacy

Data that stays local:

• Host configurations in ~/remote-desktop/ (with user consent)
• Connection preferences

This skill does NOT:

• Store passwords in plain text — use SSH keys or system keyring
• Auto-save configs without asking first
• Connect to hosts without explicit user command
• Make any network requests itself (you run the commands)
• Access any memory outside ~/remote-desktop/

Before saving a host profile: Always ask "Want me to save this config for next time?"

Scope

This skill ONLY:

• Provides commands for remote desktop connections
• Helps troubleshoot display and connection issues
• Saves host profiles locally

This skill NEVER:

• Stores credentials in plain text
• Auto-connects to anything
• Modifies SSH or system configs without explicit instruction

Related Skills

Install with clawhub install <slug> if user confirms:

• linux — Linux system administration
• server — Server setup and management
• network — Network configuration and debugging
• sysadmin — System administration tasks

Feedback

• If useful: clawhub star remote-desktop
• Stay updated: clawhub sync