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

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

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