Metadata-Version: 2.4
Name: anywhereinput
Version: 1.3.0
Summary: Remote control your PC from any browser.
Author: Z-Hussein
License-Expression: MIT
Project-URL: Homepage, https://github.com/Z-Hussein/AnywhereInput
Project-URL: Documentation, https://github.com/Z-Hussein/AnywhereInput#readme
Project-URL: Repository, https://github.com/Z-Hussein/AnywhereInput
Project-URL: Changelog, https://github.com/Z-Hussein/AnywhereInput/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Z-Hussein/AnywhereInput/issues
Keywords: remote-control,screen-sharing,websocket,remote-desktop,cross-platform
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: aiohttp>=3.14.1
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.34.2
Requires-Dist: qrcode[pil]>=8.2
Requires-Dist: mss>=10.2.0
Requires-Dist: Pillow>=12.3.0
Provides-Extra: app
Requires-Dist: PyQt6>=6.11.0; extra == "app"
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
Requires-Dist: black>=26.5.1; extra == "dev"
Requires-Dist: flake8>=7.3.0; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Dynamic: license-file

# AnywhereInput

**Control your Windows, Linux, or macOS PC from any browser.** No app install, no account, no cloud dependency.

Run a Python server on your PC and control it from any browser - mouse, keyboard, scrolling, real-time screen capture, with zero-config tunnel support.

---

## ⚡ Quick Install

### Windows
```bash
pip install anywhereinput
anywhereinput --tunnel cloudflare   # or: tailscale, pinggy, zrok2, local
```
> **Pre-requirement:** Python 3.9+ from [python.org](https://www.python.org/downloads/) — make sure to check **"Add Python to PATH"** during installation.

### macOS
```bash
pip3 install anywhereinput
anywhereinput --tunnel cloudflare
```
> **Note:** Grant "Screen Recording" access to Terminal in **System Settings > Privacy & Security**.

### Linux (Recommended: pipx)
```bash
sudo apt install pipx && pipx ensurepath   # install pipx (one-time, Ubuntu/Debian)
pipx install anywhereinput                 # installs all deps automatically
anywhereinput --tunnel cloudflare
```
> `pipx` keeps the install isolated from system Python — no dependency conflicts, no `sudo pip`.

### Linux (System pip)
```bash
# Pre-reqs for Pillow JPEG support and pyautogui X11 capture
sudo apt install libjpeg-dev zlib1g-dev libxrandr-dev
pip install anywhereinput
anywhereinput --tunnel cloudflare
```

#### Headless / Server-Only Mode
The `--app` flag requires a desktop display (X11/Wayland/Windows GUI). For headless servers, run without it:
```bash
# Server mode — works over SSH on any Linux server
anywhereinput --tunnel cloudflare   # starts the HTTP server only
# Then access from any device that can reach the URL
```

> 💡 The `--quiet` flag silences console output while keeping file logging active — useful for systemd or background processes.

---

## 🖥️ Desktop Admin App (Optional)

```bash
pip install anywhereinput[app]    # includes PyQt6
anywhereinput --app               # visual GUI - no terminal needed
```

> ⚠️ Requires a desktop display (X11/Wayland on Linux, or native Windows/macOS). On headless servers, skip `--app` and use the CLI/token API instead:
> ```bash
> anywhereinput --tunnel cloudflare   # server works fine without GUI
> ```

The desktop app lets you start/stop the server, pick tunnel providers, manage access tokens with IP allowlists, and monitor connected clients - all from a visual window.

---

## Why AnywhereInput?

| Tool | The Friction |
|------|-------------|
| TeamViewer / Chrome Remote Desktop | Account creation, bloated client, corporate telemetry |
| VNC / RDP | Port forwarding, firewall rules, VPN setup |
| **AnywhereInput** | `pip install` → paste link → control your PC |

---

## ✨ Features

- **Mouse** - move, click (left/right/middle), double-click, scroll
- **Keyboard** - key press, text typing, hotkey combos (Ctrl+C, Ctrl+Alt+Del, etc.)
- **Screen Capture** - real-time JPEG stream to browser, up to 120 FPS (adaptive)
- **Touchpad Gestures** - two-finger scroll, long-press right click, tap-to-click
- **Screen Overlay Click** - tap anywhere on the live stream to move the cursor there
- **Paint Mode** - draw directly on screen from the browser
- **Multi-monitor** - auto cursor tracking across all detected displays
- **Tunnels** - Cloudflare (free, auto-download), Tailscale P2P, Pinggy.io SSH, Zrok2, or LAN-only
- **Security** - per-token input permissions, IP allowlists (CIDR), blocked IPs, rate limiting, audit logging, auto-rotating tokens, connection request approval flow
- **Capture Modes** - Balanced, Quality, Performance, Low Bandwidth presets (custom modes saveable)

---

## 🚀 Usage

### Interactive Menu (Default)
```bash
anywhereinput
# Select tunnel provider from the menu
```

### Direct Start with Tunnel
```bash
anywhereinput --tunnel cloudflare    # Fastest global access
anywhereinput --tunnel tailscale       # Peer-to-peer on your tailnet
anywhereinput --tunnel pinggy          # SSH tunnel, works behind firewalls
anywhereinput --tunnel zrok2           # Open source, zero-trust
anywhereinput --tunnel local           # Same WiFi/LAN only
```

### Full Configuration
```bash
anywhereinput   --host 127.0.0.1   --port 8008   --fps 60   --quality 40   --scale 0.7   --monitor 1   --tunnel cloudflare
```

| Flag | Default | Description |
|------|---------|-------------|
| `--host` | `127.0.0.1` | Server bind address |
| `--port` | `8008` | HTTP/WebSocket port |
| `--fps` | `120` | Screen capture FPS (1–120) |
| `--quality` | `40` | JPEG quality (1–95, lower = faster encode) |
| `--scale` | `0.7` | Stream scale factor (0.1–1.0) |
| `--low-bandwidth` | off | Mobile data preset (15fps, q60, half scale) |
| `--no-capture` | off | Disable screen capture entirely |
| `--monitor` | `0` | Monitor index (0=auto-track, 1+=fixed) |
| `--tunnel` | interactive | Provider or `local` |
| `--help-tunnels` | - | Show tunnel provider quick help |
| `-v, --verbose` | off | DEBUG logging (repeat: `-vv`) |
| `--quiet` | off | Console silent, file only |
| `--version` | - | Show installed version |

---

## 🔒 Security

- **Auto-generated** 32-character access token on every server start
- **Per-token permissions** - grant/restrict `move`, `click`, `scroll`, `keyboard`, `screen_toggle`, `ping`
- **IP allowlists** per token - CIDR ranges and single-host support
- **Blocked IPs** - block specific IPs from individual tokens via API or admin app
- **Rate limiting** - per-IP limits on WebSocket auth, API, and token creation (localhost excluded)
- **Audit logging** - JSON-lines rotating log for all security events (token/client/IP/connection changes)
- **Token rotation** - press `n` + Enter or Ctrl+N to invalidate all previous tokens
- **Connection request approval** - clients can request access; admins approve/decline from the server
- **HTTPS/WSS** encryption when using any tunnel provider
- **Zero data** stored on external servers

> ⚠️ The `--app` flag requires a desktop display (X11 on Linux, Windows GUI, or macOS). On headless servers, run without it — the server still works perfectly:
> ```bash
> # Server mode only — no GUI needed
> anywhereinput --tunnel cloudflare
> # Access from any device that can reach the URL
> ```

---

## 📡 WebSocket API

### Authenticate
```json
{"type": "auth", "token": "***"}
```

### Send Commands
```json
{"type": "move", "mode": "relative", "dx": 10, "dy": 15}
{"type": "move", "mode": "absolute", "dx": 0.5, "dy": 0.5}
{"type": "click", "button": "left", "clicks": 1}
{"type": "scroll", "amount": 15}
{"type": "key", "key": "enter"}
{"type": "hotkey", "keys": ["ctrl", "c"]}
{"type": "screen_toggle", "enabled": true}
{"type": "screen_restart"}  # Force-rebuild capture stream (useful if frozen)
{"type": "ping"}
```

### Receive Events
```json
{"type": "screen", "data": "<base64-jpeg>"}
{"type": "screen_status", "status": "rebuilding", "message": "Reconnecting to display..."}
{"error": "capture_error", "message": "Input engine is recovering.", "recovering": true}
```

### HTTP Endpoints
| Endpoint | Description |
|----------|-------------|
| `GET /health` | Unauthenticated health/status check (uptime, clients, screen state) |
| `GET /api/screen` | Screen dimensions |
| `GET /api/engine` | Input engine + screen engine health |
| `GET /api/monitors` | All monitors + current selection |
| `POST /api/monitor/{index}` | Switch capture monitor |
| `GET /api/tokens` | List tokens (masked values) |
| `POST /api/tokens` | Create token with custom permissions |
| `PATCH /api/tokens/{token}` | Update token name/permissions |
| `DELETE /api/tokens/{token}` | Revoke a token |
| `POST /api/clients/{client_id}/kick` | Kick a client + block their IP |
| `GET /api/requests` | List pending connection requests (admin) |
| `PATCH /api/requests/{id}/approve` | Approve a connection request (admin) |
| `PATCH /api/requests/{id}/decline` | Decline a connection request (admin) |

---

## 🧰 Troubleshooting

| Problem | Fix |
|---------|-----|
| Tunnel URL not showing | Check internet; verify provider status; try another provider |
| Can't connect from device | Check firewall allows port 8008; test `http://localhost:8008` on PC first |
| Connection timeout | Verify both devices have internet; check tunnel provider status |
| Mouse lag | Reduce drag distance; try local network; lower `--fps` |
| Black cursor on capture | Install `mss`; on Linux ensure X11 display is accessible |
| Blank screen stream | Check server logs; try `--no-capture`; ensure Pillow is installed |
| Keyboard double-typing | 50ms debounce active; check mobile keyboard autocorrect |
| Zrok2 "not enabled" | Run `zrok2 enable <TOKEN>` or use `zrok2_repair.py` |
| Cloudflared missing | Auto-downloads on first run; or install manually via winget/brew |
| Screen stream frozen | Use `screen_restart` command to force-rebuild the capture stream |
| Python not found | Install Python 3.9+ from python.org, ensure it's on PATH |

---

## 📋 System Requirements

| Component | Minimum |
|-----------|---------|
| **Server OS** | Windows 10/11, Linux, macOS 12+ |
| **Python** | 3.9–3.14 |
| **Client** | Any modern browser with WebSocket + Pointer/Touch Events |
| **Internet** | Required on both devices for remote tunnel access |

---

## 📦 Dependencies Installed

Running `pip install anywhereinput` automatically installs these packages:

| Package | What It Does | Pre-requisites |
|---------|-------------|----------------|
| **pyautogui** | Keyboard/mouse automation | Linux: `libx11-dev libxrandr-dev` |
| **aiohttp** | HTTP server + WebSocket | None |
| **requests** | Tunnel provider helpers | None |
| **qrcode[pil]** | QR code generation for sharing | None |
| **mss** | Screen capture (X11/Wayland/Win/mac) | None |
| **Pillow** | JPEG encoding for screen stream | Linux: `libjpeg-dev zlib1g-dev` |
| *(Optional)* **PyQt6** | Desktop admin GUI (`pip install anywhereinput[app]`) | Desktop display required |

> 💡 On Ubuntu/Debian, the pipx method above handles all system dependencies correctly. The only pre-req is Python 3.9+.

---

## 🔗 Links

- **Website:** https://www.anywhereinput.com
- **GitHub:** https://github.com/Z-Hussein/AnywhereInput
- **PyPI:** https://pypi.org/project/anywhereinput/
- **Issues:** https://github.com/Z-Hussein/AnywhereInput/issues
- **License:** MIT

---

*Built with ❤️ for developers who value simplicity over complexity.*
