# 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 (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)**:

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

---

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

```bash
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

```bash
# 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`](crates/client/README.md) for the planned Windows client implementation.

## Development

```bash
# Build everything
cargo build

# Run tests
cargo test

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

## License

MIT