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
   │
   ▼  remote.py CLI
helios-server ──WebSocket── helios-client (Windows)

The Windows client connects to the relay server via WebSocket and registers with its device label.
The AI agent uses remote.py to issue commands — screenshots, shell commands, window management, file transfers.
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.py CLI

python remote.py devices                                    # list connected devices
python remote.py screenshot <device> screen                 # full-screen screenshot → /tmp/helios-remote-screenshot.png
python remote.py screenshot <device> <window_label>         # screenshot a specific window
python remote.py exec <device> <command...>                 # run shell command (PowerShell)
python remote.py exec <device> --timeout 600 <command...>   # with custom timeout (seconds)
python remote.py windows <device>                           # list visible windows
python remote.py focus <device> <window_label>              # focus a window
python remote.py maximize <device> <window_label>           # maximize and focus a window
python remote.py minimize-all <device>                      # minimize all windows
python remote.py prompt <device> "Please click Save"        # show MessageBox, blocks until user confirms
python remote.py prompt <device> "message" --title "Title"  # with custom dialog title
python remote.py run <device> <program> [args...]           # launch program (fire-and-forget)
python remote.py clipboard-get <device>                     # get clipboard text
python remote.py clipboard-set <device> <text>              # set clipboard text
python remote.py upload <device> <local> <remote>           # upload file to device
python remote.py download <device> <remote> <local>         # download file from device
python remote.py version <device>                           # compare relay/remote.py/client commits
python remote.py logs <device>                              # fetch last 100 lines of client log
python remote.py logs <device> --lines 200                  # custom line count

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

License

MIT

3.3 KiB Raw Blame History