# 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-remote-cli
helios-remote-relay ──WebSocket── helios-remote-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 latest/relay/cli/client commits
remote update <device>                            # update all components to latest version
remote logs <device>                              # fetch last 20 lines of client log (default)
remote logs <device> --lines 200                  # custom line count
```

### Update System

`remote update <device>` checks `version.json` on the download server for the latest available commit and updates any component that's behind:

- **Relay** — downloads new binary, replaces itself, restarts via systemd
- **Client** — downloads new binary, replaces itself, relaunches automatically
- **CLI** — downloads new binary, replaces itself, re-executes the update command

CI publishes new binaries after every push to `master` but does **not** auto-restart the relay. Updates only happen when explicitly triggered via `remote update`.

---

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

---

## Downloads

Pre-built binaries are available at:

| Binary | Platform | Link |
|---|---|---|
| `helios-remote-client` | Windows | [helios-remote-client-windows.exe](https://agent-helios.me/downloads/helios-remote/helios-remote-client-windows.exe) |
| `helios-remote-cli` | Linux | [helios-remote-cli-linux](https://agent-helios.me/downloads/helios-remote/helios-remote-cli-linux) |
| `helios-remote-cli` | Windows | [helios-remote-cli-windows.exe](https://agent-helios.me/downloads/helios-remote/helios-remote-cli-windows.exe) |

The relay server (`helios-remote-relay`) runs on the VPS and is not distributed.

---

## License

MIT