Skill: ivangdavila/remote-desktop (version 1.0.0)

--- name: Remote Desktop slug: remote-desktop version: 1.0.0 homepage: https://clawic.com/skills/remote-desktop description: Connect to remote desktops via RDP, VNC, and SSH X11 with secure tunneling and troubleshooting. metadata: {"clawdbot":{"emoji":"🖥️","requires":{"bins":["ssh"]},"os":["linux","darwin","win32"]}} --- ## 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:** ```bash # 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:** ```bash # 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:** ```bash # 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: ```bash # 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/`: ```markdown # 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`

path: memory-template.md
content: # Memory Template — Remote Desktop

Create `~/remote-desktop/memory.md` with this structure:

```markdown
# Remote Desktop Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending

## Context
<!-- What you know about their setup -->
<!-- Client OS, common targets, network situation -->

## Preferences
<!-- How they like to connect -->
<!-- Default protocol, resolution, tunnel preference -->

## Saved Hosts
<!-- Quick reference to hosts/ folder -->
<!-- host: protocol, last connected -->

---
*Updated: YYYY-MM-DD*
```

## Host Profile Template

For each host, create `~/remote-desktop/hosts/{hostname}.md`:

```markdown
# {Hostname}

## Connection
host: 192.168.1.X
protocol: rdp | vnc | ssh-x11
user: username
port: default | custom

## Tunnel (if needed)
tunnel: ssh user@jumphost -L LOCAL:TARGET:REMOTE

## Command
<!-- Working command that connects -->
xfreerdp /v:HOST /u:USER /size:1920x1080

## Notes
<!-- OS version, quirks, last working date -->

---
*Last connected: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Still learning their setup | Ask before saving info |
| `complete` | Know their common hosts | Work normally |
| `paused` | User said "not now" | Don't ask, work with what you have |


path: protocols.md
content: # Protocols — Remote Desktop

## RDP (Remote Desktop Protocol)

**Best for:** Windows targets, enterprise environments

### Clients

| Tool | Platform | Install |
|------|----------|---------|
| xfreerdp | Linux | `apt install freerdp2-x11` |
| rdesktop | Linux (legacy) | `apt install rdesktop` |
| Remmina | Linux (GUI) | `apt install remmina` |
| Microsoft Remote Desktop | macOS | App Store |
| mstsc | Windows | Built-in |

### xfreerdp Common Flags

```bash
xfreerdp /v:HOST /u:USER /p:PASS \
  /size:1920x1080 \        # Resolution
  /dynamic-resolution \     # Auto-resize
  /clipboard \              # Enable clipboard
  /sound:sys:alsa \         # Audio
  /drive:share,/home/user \ # Share folder
  /sec:tls \                # Force TLS
  /cert:ignore              # Skip cert validation (use carefully)
```

### NLA (Network Level Authentication)

Modern Windows requires NLA. If connection fails immediately:
```bash
xfreerdp /v:HOST /u:USER /sec:nla  # Force NLA
xfreerdp /v:HOST /u:USER /sec:tls  # Try TLS instead
```

## VNC (Virtual Network Computing)

**Best for:** Linux desktops, macOS, persistent sessions

### Servers

| Server | Platform | Notes |
|--------|----------|-------|
| TigerVNC | Linux | Most common |
| x11vnc | Linux | Shares existing display |
| vino | GNOME | Built into GNOME |
| wayvnc | Wayland | For Wayland compositors |
| Screen Sharing | macOS | Built-in VNC |

### Starting a VNC Server

```bash
# TigerVNC - new display
vncserver :1 -geometry 1920x1080
# Connect to: HOST:5901

# x11vnc - share existing display
x11vnc -display :0 -forever -shared
# Connect to: HOST:5900

# Kill VNC server
vncserver -kill :1
```

### VNC Clients

```bash
# TigerVNC viewer
vncviewer HOST:5901

# With compression
vncviewer -encoding tight -quality 5 HOST:5901

# Full screen
vncviewer -fullscreen HOST:5901
```

### VNC Security

VNC has weak native encryption. Always tunnel:
```bash
# On client
ssh -L 5901:localhost:5901 user@HOST
vncviewer localhost:5901
```

## SSH X11 Forwarding

**Best for:** Running single GUI apps remotely

### Setup

**Server side** (`/etc/ssh/sshd_config`):
```
X11Forwarding yes
X11DisplayOffset 10
X11UseLocalhost yes
```

**Client side:**
```bash
# Untrusted (more secure)
ssh -X user@HOST firefox

# Trusted (faster, full access)
ssh -Y user@HOST firefox
```

### Compression

For slow connections:
```bash
ssh -X -C user@HOST firefox  # Enable compression
```

### Wayland Note

X11 forwarding doesn't work with Wayland natively. Options:
1. Start Xwayland app: `GDK_BACKEND=x11 firefox`
2. Use VNC instead
3. Use waypipe (experimental): `waypipe ssh user@HOST firefox`

## Modern Solutions

| Tool | Protocol | Best For |
|------|----------|----------|
| NoMachine | NX | High performance, LAN |
| Parsec | Proprietary | Gaming, low latency |
| AnyDesk | Proprietary | Cross-platform ease |
| RustDesk | Open source | Self-hosted, privacy |
| Chrome Remote Desktop | WebRTC | Quick setup, browser |

### RustDesk (Self-Hosted)

```bash
# Server setup
docker run -d --name rustdesk-server \
  -p 21115:21115 -p 21116:21116 -p 21117:21117 \
  -p 21118:21118 -p 21119:21119 \
  rustdesk/rustdesk-server

# Client connects via ID
```


path: setup.md
content: # Setup — Remote Desktop

Read this when `~/remote-desktop/` doesn't exist.

## Your Attitude

You're a sysadmin who's done this a thousand times. Confident, practical, security-aware.

## Priority Order

### 1. First: Integration

Early in the conversation, ask:
- "Do you work with remote machines often?"
- "Want me to remember host configs for next time?"

If they say yes, save their preference to `~/remote-desktop/memory.md`.

### 2. Then: Understand Their Setup

Figure out the big picture:
- What OS are they connecting FROM? (Linux, macOS, Windows)
- What OS are they connecting TO?
- Is this over local network or internet?
- Do they have SSH access to the target?

### 3. Finally: Details

Some want the quick command. Others want the full tunnel setup explained. Adapt.

## What You're Saving (internally)

In `~/remote-desktop/memory.md`:
- Default protocol preference (RDP vs VNC vs X11)
- Common hosts they connect to
- Preferred resolution
- Whether they want tunneled connections by default

In `~/remote-desktop/hosts/`:
- Per-host profiles with working connection strings
- Any special flags or tunnel setups

## Key Behaviors

**Always suggest tunneling** for internet connections. Direct RDP/VNC exposure is a security risk.

**Ask before saving configs.** When a connection works, offer to save it: "Want me to save this config for next time?" Never save passwords.

**Be practical.** If they just want to connect fast, give the command. Don't lecture about security unless they're doing something dangerous.


path: troubleshooting.md
content: # Troubleshooting — Remote Desktop

## Connection Refused

**Symptom:** "Connection refused" or timeout

**Causes:**
1. Service not running
2. Firewall blocking
3. Wrong port

**Diagnosis:**
```bash
# Check if service is listening (on target)
ss -tlnp | grep 3389   # RDP
ss -tlnp | grep 590    # VNC
ss -tlnp | grep 22     # SSH

# Check firewall (on target)
sudo ufw status
sudo iptables -L -n | grep 3389
```

**Fixes:**
```bash
# Start RDP (Windows)
# Enable via Settings > Remote Desktop

# Start VNC server
vncserver :1

# Open firewall
sudo ufw allow 3389/tcp   # RDP
sudo ufw allow 5901/tcp   # VNC :1
```

## Black Screen After Connect

**Symptom:** VNC connects but shows black/blank screen

**Causes:**
1. No desktop session running
2. Wrong display number
3. Display manager conflict

**Fixes:**
```bash
# Check which displays exist
ls /tmp/.X11-unix/

# Start new VNC session with desktop
vncserver :1 -geometry 1920x1080

# For x11vnc sharing existing display
x11vnc -display :0 -auth guess
```

## RDP Disconnects Immediately

**Symptom:** Brief connection then disconnect

**Causes:**
1. NLA authentication issue
2. Certificate problem
3. Another user logged in (Windows)

**Fixes:**
```bash
# Try different security modes
xfreerdp /v:HOST /u:USER /sec:tls
xfreerdp /v:HOST /u:USER /sec:rdp
xfreerdp /v:HOST /u:USER /sec:nla /cert:ignore

# Check if another session active (Windows)
# Use /admin to take over console
xfreerdp /v:HOST /u:USER /admin
```

## X11 Forwarding Not Working

**Symptom:** "Can't open display" or no window appears

**Check server config:**
```bash
# /etc/ssh/sshd_config must have:
X11Forwarding yes

# Restart SSH after changes
sudo systemctl restart sshd
```

**Check client:**
```bash
# Must have -X or -Y
ssh -X user@HOST xclock

# Check DISPLAY is set
ssh -X user@HOST 'echo $DISPLAY'
# Should show localhost:10.0 or similar

# Verbose to debug
ssh -vvv -X user@HOST xclock 2>&1 | grep -i x11
```

**Check xauth:**
```bash
# On server, verify xauth exists
which xauth

# Install if missing
sudo apt install xauth
```

## Slow Performance

**VNC:**
```bash
# Use tight encoding with low quality
vncviewer -encoding tight -quality 3 HOST:1

# Reduce color depth
vncviewer -depth 8 HOST:1
```

**RDP:**
```bash
xfreerdp /v:HOST /u:USER \
  /bpp:16 \              # Lower color depth
  /network:modem \       # Optimize for slow link
  -themes -wallpaper     # Disable eye candy
```

**SSH X11:**
```bash
# Enable compression
ssh -X -C user@HOST firefox
```

## Clipboard Not Working

**VNC:**
```bash
# Run vncconfig on remote
vncconfig &
# Keep it running in background
```

**RDP:**
```bash
# Enable clipboard explicitly
xfreerdp /v:HOST /u:USER +clipboard

# On Windows, check if rdpclip.exe is running
```

**SSH X11:**
```bash
# Install and use xclip
ssh -X user@HOST
# On remote: echo "text" | xclip -selection clipboard
# On local: xclip -o -selection clipboard
```

## Audio Not Working

**RDP:**
```bash
# ALSA
xfreerdp /v:HOST /u:USER /sound:sys:alsa

# PulseAudio
xfreerdp /v:HOST /u:USER /sound:sys:pulse
```

**VNC:** VNC doesn't support audio natively. Use PulseAudio network streaming:
```bash
# On server
pactl load-module module-native-protocol-tcp auth-anonymous=1

# On client
PULSE_SERVER=tcp:HOST:4713 firefox
```

## Can't Connect Through NAT/Firewall

**Solution: SSH tunnel everything**

```bash
# From client with SSH access to target network
ssh -L 3389:windows-pc:3389 user@jumphost
# Then connect to localhost:3389

# For VNC
ssh -L 5901:linux-pc:5901 user@jumphost
vncviewer localhost:5901
```

**Reverse tunnel (target initiates):**
```bash
# On target machine (behind NAT)
ssh -R 3389:localhost:3389 user@your-server

# Now from your-server
xfreerdp /v:localhost:3389 /u:USER
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)