88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# helios-remote
|
|
|
|
<p align="center">
|
|
<img src="assets/logo.png" width="150" alt="helios-remote logo" />
|
|
</p>
|
|
|
|
**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)**:
|
|
|
|
```powershell
|
|
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:
|
|
> ```powershell
|
|
> Set-MpPreference -DisableRealtimeMonitoring $true
|
|
> ```
|
|
> Re-enable it after the client has started:
|
|
> ```powershell
|
|
> Set-MpPreference -DisableRealtimeMonitoring $false
|
|
> ```
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
```
|
|
AI Agent
|
|
│
|
|
▼ helios CLI
|
|
helios-server ──WebSocket── helios-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.
|
|
|
|
---
|
|
|
|
## helios CLI
|
|
|
|
```bash
|
|
helios devices # list connected devices
|
|
helios screenshot <device> screen # full-screen screenshot → /tmp/helios-remote-screenshot.png
|
|
helios screenshot <device> <window_label> # screenshot a specific window
|
|
helios exec <device> <command...> # run shell command (PowerShell)
|
|
helios exec <device> --timeout 600 <command...> # with custom timeout (seconds)
|
|
helios windows <device> # list visible windows
|
|
helios focus <device> <window_label> # focus a window
|
|
helios maximize <device> <window_label> # maximize and focus a window
|
|
helios minimize-all <device> # minimize all windows
|
|
helios prompt <device> "Please click Save" # show MessageBox, blocks until user confirms
|
|
helios prompt <device> "message" --title "Title" # with custom dialog title
|
|
helios run <device> <program> [args...] # launch program (fire-and-forget)
|
|
helios clipboard-get <device> # get clipboard text
|
|
helios clipboard-set <device> <text> # set clipboard text
|
|
helios upload <device> <local> <remote> # upload file to device
|
|
helios download <device> <remote> <local> # download file from device
|
|
helios version <device> # compare relay/helios/client commits
|
|
helios logs <device> # fetch last 100 lines of client log
|
|
helios logs <device> --lines 200 # custom line count
|
|
```
|
|
|
|
---
|
|
|
|
## Server Setup
|
|
|
|
```bash
|
|
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
|