helios-remote

AI-first remote control tool — a relay server + Windows client written in Rust. Lets an AI agent (or any HTTP client) take full control of a remote Windows machine via a lightweight WebSocket relay.

Quick Connect

Run this in PowerShell (as Admin):

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:

Set-MpPreference -DisableRealtimeMonitoring $true

Re-enable it after the client has started:

Set-MpPreference -DisableRealtimeMonitoring $false

---

Architecture

helios-remote/
├── crates/
│   ├── common/     # Shared protocol types, WebSocket message definitions
│   ├── server/     # Relay server (REST API + WebSocket hub)
│   └── client/     # Windows client — Phase 2 (stub only)
├── Cargo.toml      # Workspace root
└── README.md

How It Works

AI Agent
   │  REST API (X-Api-Key)
   ▼
helios-server  ──WebSocket──  helios-client (Windows)
   │                               │
POST /sessions/:id/screenshot      │  Captures screen → base64 PNG
POST /sessions/:id/exec            │  Runs command in persistent shell
POST /sessions/:id/click           │  Simulates mouse click
POST /sessions/:id/type            │  Types text

1. The Windows client connects to the relay server via WebSocket and sends a Hello message.
2. The AI agent calls the REST API to issue commands.
3. The relay server forwards commands to the correct client session and streams back responses.

Server

REST API

All endpoints require the X-Api-Key header.

Method	Path	Description
GET	/sessions	List all connected clients
POST	/sessions/:id/screenshot	Request a screenshot (returns base64 PNG)
POST	/sessions/:id/exec	Execute a shell command
POST	/sessions/:id/click	Simulate a mouse click
POST	/sessions/:id/type	Type text
POST	/sessions/:id/label	Rename a session
GET	/sessions/:id/windows	List all windows
POST	/sessions/:id/windows/minimize-all	Minimize all windows
POST	/sessions/:id/windows/:window_id/focus	Focus a window
POST	/sessions/:id/windows/:window_id/maximize	Maximize and focus a window
POST	/sessions/:id/run	Launch a program (fire-and-forget)
GET	/sessions/:id/clipboard	Get clipboard contents
POST	/sessions/:id/clipboard	Set clipboard contents
GET	/sessions/:id/version	Get client version
POST	/sessions/:id/upload	Upload a file to the client
GET	/sessions/:id/download?path=...	Download a file from the client

WebSocket

Clients connect to ws://host:3000/ws. No auth required at the transport layer — the server trusts all WS connections as client agents.

Running the Server

HELIOS_API_KEY=your-secret-key HELIOS_BIND=0.0.0.0:3000 cargo run -p helios-server

Environment variables:

Variable	Default	Description
HELIOS_API_KEY	dev-secret	API key for REST endpoints
HELIOS_BIND	0.0.0.0:3000	Listen address
RUST_LOG	helios_server=debug	Log level

Example API Usage

# List sessions
curl -H "X-Api-Key: your-secret-key" http://localhost:3000/sessions

# Take a screenshot
curl -s -X POST -H "X-Api-Key: your-secret-key" \
  http://localhost:3000/sessions/<session-id>/screenshot

# Run a command
curl -s -X POST -H "X-Api-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "whoami"}' \
  http://localhost:3000/sessions/<session-id>/exec

# Click at coordinates
curl -s -X POST -H "X-Api-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"x": 100, "y": 200, "button": "left"}' \
  http://localhost:3000/sessions/<session-id>/click

remote.py CLI

The skills/helios-remote/remote.py script provides a simple CLI wrapper around the REST API.

Label Routing

All commands accept either a UUID or a label name as session_id. If the value is not a UUID, the script resolves it by looking up the label across all connected sessions:

python remote.py screenshot "Moritz PC"   # resolves label → UUID automatically
python remote.py exec "Moritz PC" whoami

Commands

python remote.py sessions                          # list sessions
python remote.py screenshot <session>              # capture screenshot → /tmp/helios-remote-screenshot.png
python remote.py exec <session> <command...>       # run shell command (PowerShell, no wrapper needed)
python remote.py exec <session> --timeout 600 <command...>  # with custom timeout (seconds, default: 30)
python remote.py prompt <session> "Please click Save, then OK"  # ask user to do something manually
python remote.py click <session> <x> <y>           # mouse click
python remote.py type <session> <text>             # keyboard input
python remote.py windows <session>                 # list windows
python remote.py find-window <session> <title>     # filter windows by title substring
python remote.py minimize-all <session>            # minimize all windows
python remote.py focus <session> <window_id>       # focus window
python remote.py maximize <session> <window_id>    # maximize and focus window
python remote.py run <session> <program> [args...] # launch program (fire-and-forget)
python remote.py clipboard-get <session>           # get clipboard text
python remote.py clipboard-set <session> <text>    # set clipboard text
python remote.py upload <session> <local> <remote> # upload file
python remote.py download <session> <remote> <local> # download file
python remote.py screenshot-window <session> <window_id_or_title>  # screenshot a specific window
python remote.py screenshot-window <session> <title> --output /tmp/out.png  # custom output path
python remote.py wait-for-window <session> <title>            # poll until window appears
python remote.py wait-for-window <session> <title> --timeout 60  # custom timeout (default: 30s)
python remote.py label <session> <new_name>        # assign a human-readable name to session
python remote.py status <session>                  # compare relay / remote.py / client commit
python remote.py logs <session>                    # fetch last 100 lines of client log
python remote.py logs <session> --lines 200        # custom line count
python remote.py version <session>                 # client version
python remote.py server-version                    # server version (no auth required)

Client (Phase 2)

See crates/client/README.md for the planned Windows client implementation.

Development

# Build everything
cargo build

# Run tests
cargo test

# Run server in dev mode
RUST_LOG=debug cargo run -p helios-server

License

MIT