# 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