114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
# helios-remote
|
|
|
|
<p align="center">
|
|
<img src="assets/logo.png" width="150" style="border-radius: 50%;" 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.
|
|
|
|
## 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
|