116 lines
4.4 KiB
Markdown
116 lines
4.4 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-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
|
|
|
|
|
|
|