helios-remote

AI-first remote control tool — a relay server + Windows client written in Rust. Lets an AI agent take full control of a remote Windows machine via a lightweight WebSocket relay.

Quick Connect

Run this in PowerShell (as Admin):

irm https://raw.githubusercontent.com/agent-helios/helios-remote/master/scripts/install.ps1 | iex

Windows Defender notice: Defender may flag the executable as unknown. Temporarily disable real-time protection before running:

Set-MpPreference -DisableRealtimeMonitoring $true

Re-enable it after the client has started:

Set-MpPreference -DisableRealtimeMonitoring $false

---

How It Works

AI Agent
   │
   ▼  helios-remote-cli
helios-remote-relay ──WebSocket── helios-remote-client (Windows)

1. The Windows client connects to the relay server via WebSocket and registers with its device label.
2. The AI agent uses helios to issue commands — screenshots, shell commands, window management, file transfers.
3. The relay server forwards everything to the correct client and streams back responses.

Device labels are the sole identifier. Only one client instance can run per device.

---

remote CLI

remote devices                                    # list connected devices
remote screenshot <device> screen                 # full-screen screenshot → /tmp/helios-remote-screenshot.png
remote screenshot <device> <window_label>         # screenshot a specific window
remote exec <device> <command...>                 # run shell command (PowerShell)
remote exec <device> --timeout 600 <command...>   # with custom timeout (seconds)
remote windows <device>                           # list visible windows
remote focus <device> <window_label>              # focus a window
remote maximize <device> <window_label>           # maximize and focus a window
remote minimize-all <device>                      # minimize all windows
remote inform <device> "Something happened"       # notify user (fire-and-forget, no response)
remote inform <device> "message" --title "Title"  # with custom dialog title
remote run <device> <program> [args...]           # launch program (fire-and-forget)
remote clipboard-get <device>                     # get clipboard text
remote clipboard-set <device> <text>              # set clipboard text
remote upload <device> <local> <remote>           # upload file to device
remote download <device> <remote> <local>         # download file from device
remote version <device>                           # compare latest/relay/cli/client commits
remote update <device>                            # update all components to latest version
remote logs <device>                              # fetch last 20 lines of client log (default)
remote logs <device> --lines 200                  # custom line count

Update System

remote update <device> checks version.json on the download server for the latest available commit and updates any component that's behind:

• Relay — downloads new binary, replaces itself, restarts via systemd
• Client — downloads new binary, replaces itself, relaunches automatically
• CLI — downloads new binary, replaces itself, re-executes the update command

CI publishes new binaries after every push to master but does not auto-restart the relay. Updates only happen when explicitly triggered via remote update.

---

Server Setup

HELIOS_API_KEY=your-secret-key HELIOS_BIND=0.0.0.0:3000 cargo run -p helios-server

Variable	Default	Description
HELIOS_API_KEY	dev-secret	API key
HELIOS_BIND	0.0.0.0:3000	Listen address
RUST_LOG	helios_server=debug	Log level

---

Downloads

Pre-built binaries are available at:

Binary	Platform	Link
helios-remote-client	Windows	helios-remote-client-windows.exe
helios-remote-cli	Linux	helios-remote-cli-linux
helios-remote-cli	Windows	helios-remote-cli-windows.exe

The relay server (helios-remote-relay) runs on the VPS and is not distributed.

---

License

MIT