# 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
   │
   ▼  remote.py 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 `remote.py` 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.py CLI

```bash
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

```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