# 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 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.

---

## remote CLI

```bash
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 relay/helios/client commits
remote logs <device>                              # fetch last 20 lines of client log (default)
remote 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
