Initial implementation: relay server + common protocol + client stub

README.md

@@ -0,0 +1,110 @@
+# 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.
+
+## 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