--- name: rockdesk-remote-control description: >- Control and automate a remote computer through the RockDesk CLI (`rds` / `rockdesk`), addressed by a 9-digit RockDesk ID. Run shell commands, copy files, mount a remote directory as a local folder, sync the clipboard, drive screen/mouse/keyboard, and forward ports / serial ports / USB devices / an IP tunnel — all peer-to-peer, no sshd or open inbound port on the remote. Use whenever the user wants to inspect, operate, or automate a remote machine — a headless server or a GUI desktop — over RockDesk. Triggers: "control my other computer", "on the remote machine…", "screenshot the remote", "mount the remote dir", "forward the serial/USB port", "run this over RockDesk", a bare 9-digit RockDesk ID plus an action. --- # RockDesk CLI & Agent Skill RockDesk is a cross-platform remote-desktop tool. Beyond the GUI it ships a scriptable command line — `rds` / `rockdesk` — that lets Codex, Claude, Trae, WorkBuddy, or another AI agent drive a remote machine headlessly: run shell commands, share directories, copy files, forward ports / serial / USB, tunnel IP, and control screen, mouse, keyboard and clipboard. Install RockDesk 1.2.3 or newer on both machines, then use the commands below. `rockdesk` and `rds` are the same binary; `rds` is a thin wrapper for `rockdesk --rds`. Every machine is addressed by its 9-digit **RockDesk ID** (shown in the app). The first command to an ID auto-connects a background session; every later command reuses that one connection, so the first is a bit slow (a few seconds) and the rest are near-instant. No GUI window opens. ## Two command surfaces - **`rds `** — remote control of one machine: shell, file copy, directory mount, clipboard, and screen / mouse / keyboard. Auto-connects and reuses one peer-to-peer connection. - **`rockdesk --`** — device forwarding (port / serial / USB / IP tunnel) and low-level primitives, via the local RockDesk background service (it ships with the app). Authentication uses the peer's permanent password (set in the app). Pass it as the trailing `[password]` where shown, or let the CLI prompt once and cache it. Do not guess passwords. ## For agents (read first) - **Shell first, GUI second.** Anything you can do in a shell, do with `shell -c` — faster, deterministic, no coordinates. Reach for mouse/keyboard only for GUI-only things (a native app with no CLI, a button in a web page). - **Interactive `rds shell` is for humans, not agents** — always pass `-c ""`. - **Never run `rds disconnect`.** The background connection is a *shared* per-peer daemon — other tasks (and any mounted folder) reuse it. It self-heals a flaky channel on the next command; if a command hangs or errors, just run it again. There is nothing to clean up between commands. - **GUI-only work: observe → act → verify.** Screenshot to a file and read the image; find the target's pixel; click/type/key; screenshot again to confirm. Never click blind. - **Safety.** Only operate machines the user owns or is authorized to control. Before any destructive/irreversible action (deleting, overwriting, `sudo` that restarts services, sending messages, purchases), state what you will run and get confirmation. Read-only inspection needs none. Never enter the user's passwords/secrets into remote fields. --- ## Terminal — run commands & interactive shells (终端) ``` rds shell -c "" Run one command on the remote; returns its stdout+stderr and exits with the command's own code (so `&&`, `||`, and `if rds shell -c "test ..."` all work like ssh). Full login shell / profile is sourced (conda, pixi, PATH), so use bash syntax directly. Chain your logic in one command (`cd /var/log && grep ... x`, pipes, `&&`, `;`) rather than many round-trips. Piped local stdin is forwarded to the remote command (buffered, up to 4 MB): echo hi | rds shell -c "cat" cat f | rds shell -c "wc -l" No timeout by default — a long clone/build runs to completion; pass `--timeout ` to cap it. rds spawn "" Launch a long-running / background process that OUTLIVES the terminal (setsid + nohup + detached I/O into a log file). Returns the pid and log path. Use it for servers, watchers, training runs: rds spawn "python train.py" → spawned pid 12345 · log: /tmp/rds-spawn-.log rds shell Interactive TTY for a human (readline, tab-completion, colors, live resize), exactly like ssh. Exit with Ctrl-C twice. (Agents: use `-c` instead.) ``` ## Directory sharing — mount a remote folder (目录共享) Mount a remote directory as a local folder over RockDesk's own encrypted channel — SSHFS-like, but with no sshd on the remote. ``` rds mount :/remote/dir Mount the remote directory at (auto-created). Reads AND writes; Finder / grep / editors / builds see a normal folder. rds mount :/home/user/project ~/proj rds mount :/var/log ~/peer_logs # 2nd dir: near-instant rds umount Unmount one directory (only what you mounted — the user may be using theirs). ``` - **One connection, many directories** — every mount to the same peer shares one channel; the first pays the connect, each further directory attaches in well under a second. - **Survives network blips** — on a drop the daemon reconnects and resumes all mounts by itself; in-flight file ops retry (NFS-hard semantics). - **Platforms** — client side Windows (WinFsp), macOS (kext-less fuse-t), and Linux (kernel FUSE). The GUI's "Mount folder" menu drives the same mechanism. **cp vs mount**: `cp` for one-shot bulk transfer (faster for big files); `mount` to *work inside* the remote tree (many small reads, in-place edits, a local tool that needs a real path — grep/IDE/build). ## File copy (文件传输) ``` rds cp Copy a file or directory; the REMOTE side is prefixed with ':'. upload: rds cp ./a.tgz :/home/u/a.tgz download: rds cp :/etc/hosts ./hosts dir: rds cp ./dir :/tmp/dir (recursive) Same-name files are overwritten (scp semantics). Prints `… complete: …` to stdout and exits 0 on success — loop on that to retry idempotently: until rds cp ./a :/b; do sleep 2; done ``` ## Port forwarding — TCP tunnel to a remote service (端口转发) Expose a service reachable from the remote as a local port (SSH `-L` style). ``` rockdesk --port-forward [remote-host] [password] Listen on localhost: and forward every connection through the peer to : (remote-host defaults to localhost, i.e. a service on the remote machine itself). # reach the remote's own VNC (127.0.0.1:5900) at local :15900 rockdesk --port-forward 208157220 15900 5900 # reach a database the remote can see (db.internal:5432) at local :15432 rockdesk --port-forward 208157220 15432 5432 db.internal ``` ## IP tunnel — route traffic out through a remote gateway (IP 隧道 / RockTun) Send local traffic out through a remote machine (IP avatar / private network). ``` rockdesk --tun-connect [password] Bring up the tunnel. rockdesk --tun-status Status JSON (running / rtt / bytes). rockdesk --tun-connections Connections carried by the tunnel. rockdesk --tun-disconnect Tear it down. ``` ## Serial forwarding — a remote serial port, locally (串口转发) Map a serial port on the remote onto the local machine. ``` rockdesk --serial-list List LOCAL serial ports. rockdesk --serial-list-remote [password] List the remote's ports. rockdesk --serial-connect [baud] [password] Start forwarding a remote port, e.g.: rockdesk --serial-connect 208157220 /dev/ttyUSB0 115200 rockdesk --serial-status Active forwards (+ forward_id). rockdesk --serial-disconnect Stop one forward. ``` ## USB forwarding — attach a remote USB device (USB 转发 / USB/IP) Attach a USB device plugged into the remote to the local machine. Receiving side is Linux or Windows (needs usbipd-win); macOS cannot be the receiver. ``` rockdesk --usbip-list List LOCAL USB devices. rockdesk --usbip-list-remote [password] List the remote's devices (+ busid). rockdesk --usbip-attach [password] Attach a remote device by busid, e.g.: rockdesk --usbip-attach 208157220 1-1.2 rockdesk --usbip-status Active attachments (+ forward_id). rockdesk --usbip-detach Detach one device. ``` ## Screen, mouse, keyboard, clipboard ``` rds info List displays (index, WxH, name). rds screenshot -o [-d ] [-R ] Save a PNG (opaque RGB) — then read the image. rds click [--right] [--double] Click at absolute pixel (from top-left). rds move Move the cursor. rds type Type into the focused field (click to focus first). rds key [+...] Press a key/chord (e.g. Return, ctrl+c, cmd+s). rds scroll Scroll wheel (dy>0 = down). rds clipboard set | get Remote clipboard text. rds clipboard set-image | get-image [out.png] Remote clipboard image. ``` `clipboard get` / `get-image` return what the remote copied *after* you connected (it syncs on change); if empty, read the file with `shell -c` instead. ## Connection model (what reuses, what opens fresh) One shared background daemon per peer id, used by every `rds` invocation from every terminal. Inside it, ONE channel per service type, each created lazily on first use and then reused; the transport (TCP / UDP-KCP) keeps them alive through jitter and self-heals a dropped channel on the next command. | Channel | Carries | |----------|------------------------------------------------------------| | control | info, screenshot, click/move/type/key/scroll, clipboard | | terminal | every `shell -c`, `spawn`, and the interactive shell | | file | every `cp` | | fs | ALL mounted directories, multiplexed | `--serial-*`, `--usbip-*`, `--tun-*`, and `--port-forward` need the local RockDesk background service running (it launches with the app). The `rds` remote-control commands do not — they connect peer-to-peer. --- *RockDesk — https://rockdesk.io*