Metadata-Version: 2.4
Name: agent2win
Version: 1.1.3
Summary: Universal Bridge & Autonomous Agent Runtime Between Web/Cloud AI Gateways & Windows OS
Author: agent2win Developers
License: MIT
Project-URL: Homepage, https://github.com/harikasinkaya/agent2win
Project-URL: Documentation, https://github.com/harikasinkaya/agent2win#readme
Project-URL: Repository, https://github.com/harikasinkaya/agent2win.git
Project-URL: Issues, https://github.com/harikasinkaya/agent2win/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
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: Operating System :: Microsoft :: Windows
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: mss>=9.0.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pyperclip>=1.8.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pycaw>=20230407; platform_system == "Windows"
Requires-Dist: comtypes>=1.4.1; platform_system == "Windows"
Requires-Dist: pyvda>=0.6.0; platform_system == "Windows"
Requires-Dist: pystray>=0.19.0; platform_system == "Windows"
Requires-Dist: win10toast>=0.9; platform_system == "Windows"
Dynamic: license-file

# 🚀 agent2win

<div align="center">

### Universal Bridge Between Web / Cloud AI Agents & Windows OS

**Control your Windows PC or Server directly from AI agents (Arena.ai, ChatGPT Custom Actions, Claude, Grok, LangChain, CrewAI) via secure REST API & WebSocket.**

[![PyPI Version](https://img.shields.io/pypi/v/agent2win.svg)](https://pypi.org/project/agent2win/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/harikasinkaya/agent2win/blob/main/LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
[![Platform: Windows Only](https://img.shields.io/badge/platform-Windows%2010%2F11%2FServer-0078d4.svg)](https://microsoft.com/windows)
[![API: REST & WebSocket](https://img.shields.io/badge/API-REST%20%26%20WebSocket-green.svg)](https://github.com/harikasinkaya/agent2win/blob/main/AGENT_PROTOCOL.md)

</div>

---

> ⚠️ **Platform Requirement:**  
> **agent2win is designed exclusively for Microsoft Windows (Windows 10, Windows 11, and Windows Server 2016+).** It utilizes native Win32 APIs, COM interfaces (`pyvda`, `pycaw`), and Windows system controls.

---

> [!WARNING]
> **Never expose agent2win to the public internet without an API key.**  
> Unrestricted mode permits remote command execution, filesystem access, input control, and system administration without interactive approval. Use `--unrestricted` only in trusted environments and stop the server immediately after use. Do not share your real API keys in public prompts, screenshots, or GitHub issues.

---

## 📖 Overview

**agent2win** is a lightweight, high-performance middleware server for Windows. It exposes a unified REST & WebSocket API, instantly accessible over the public internet through automatic Cloudflare or ngrok tunnels with zero router configuration.

Whether you are using AI environments executing curl requests in their sandboxes (like **Arena.ai**), connecting Custom Actions via **ChatGPT**, or driving automation loops with **Claude**, **agent2win** gives external models complete programmatic control over your Windows desktop.

```
┌──────────────────────────────────────────────────────────────────┐
│ Web & Cloud AI Ecosystem                                         │
│ • Arena.ai & curl-capable agents        • chatgpt.com (Actions)  │
│ • grok.com / xAI                        • claude.ai / Anthropic  │
│ • Autonomous Frameworks (LangChain, CrewAI, AutoGen, AutoGPT)    │
└─────────────────────────────────┬────────────────────────────────┘
                                  │ HTTPS / WSS (API Key Auth)
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ Cloudflare / ngrok Public Tunnel (Zero Port-Forwarding)          │
└─────────────────────────────────┬────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────┐
│ agent2win Server (:7770)                                         │
├─────────────────────────────────┬────────────────────────────────┤
│ • Screen & Window Capture       │ • Mouse & Keyboard Emulation   │
│ • Shell & Command Runner        │ • Virtual Desktop Isolation    │
│ • Filesystem & Registry         │ • Process & Service Manager    │
│ • Clipboard & Audio Controls    │ • Security & Approval Layer    │
└─────────────────────────────────┴────────────────────────────────┘
```

---

## ✨ Key Features

- 🌐 **Web AI Compatibility**: Connect web-based models (**ChatGPT Actions**, **Claude**, **Grok**, **Arena.ai**) to operate your Windows machines.
- ⚡ **Zero-Config Public Tunnel**: Instant public HTTPS endpoint generated automatically using Cloudflare Tunnel (`cloudflared`) or `ngrok`. No static IP or port forwarding required.
- 🖥️ **Virtual Desktop Isolation**: Create dedicated secondary virtual desktops (`/api/desktops`). The agent works autonomously on Desktop 2 without interfering with your active tasks on Desktop 1.
- 📸 **Vision & Window Capture**: Full display screenshots or targeted window-handle (`hwnd`) captures in Base64 format for visual reasoning.
- 🖱️ **Hardware Input Emulation**: Mouse click, drag, scroll, and keyboard typing with complete Unicode / international character support.
- 💻 **OS & System Administration**: Run PowerShell/CMD scripts, manage filesystem (read/write/search/mkdir), list/kill processes, inspect Windows Services, and edit Registry keys.
- 🔒 **Security Layer**: Bearer token authentication (`Authorization: Bearer <key>`), real-time desktop approval prompts for risky commands, system tray killswitch, and audit logging.

---

## ⚡ Quick Start

### 1. Install from PyPI

```bash
pip install agent2win
```

### 2. Run Server (Recommended Secure Public Tunnel)

```bash
agent2win --key YOUR_STRONG_RANDOM_API_KEY --tunnel cloudflared
```

The console displays your live public HTTPS tunnel:

```text
🌐 Public Tunnel : https://xxxx.trycloudflare.com
```

### Local-Only Usage (No Public Tunnel)

```bash
agent2win --no-tunnel
```

---

## 🤖 Using With AI Agents & curl-Capable Platforms (Arena.ai, ChatGPT, Claude, Grok)

### 📋 Direct Prompt to Connect Any AI / Agent
Copy and paste this prompt directly into **Arena.ai, ChatGPT, Claude, Grok, or any AI capable of web fetching or executing curl requests**:

```markdown
Read the official agent2win control protocol from this URL:
https://raw.githubusercontent.com/harikasinkaya/agent2win/refs/heads/main/AGENT_PROTOCOL.md

You are now an autonomous Windows controller agent.
My agent2win server URL is: <PASTE_YOUR_TUNNEL_URL_HERE>
My API key is: <PASTE_YOUR_API_KEY_HERE>

Always include the header `Authorization: Bearer <API_KEY>` in all requests.
Please inspect the system info, capture the screen, and follow my instructions to control my Windows machine.
```

### ⚡ Example curl Commands (With Authentication)

```bash
# 1. Get system info
curl "https://xxxx.trycloudflare.com/api/info" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Capture desktop screenshot (Base64 JPEG)
curl "https://xxxx.trycloudflare.com/api/screen" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Execute command
curl -X POST "https://xxxx.trycloudflare.com/api/command" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"whoami"}'

# 4. Click at screen coordinates
curl -X POST "https://xxxx.trycloudflare.com/api/mouse/click" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300, "button": "left"}'

# 5. Type Unicode text
curl -X POST "https://xxxx.trycloudflare.com/api/keyboard/type" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from AI Agent 🚀", "unicode": true}'

# 6. Write file (supports forward and backslashes)
curl -X POST "https://xxxx.trycloudflare.com/api/files/write" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "C:\\Users\\Public\\test.txt", "content": "agent2win test"}'
```

---

## 🤖 WebAPI Agent Mode (OpenAI-Compatible Gateways & GUI)

agent2win includes an autonomous agent runtime that transforms **any standard OpenAI-compatible LLM gateway** (DeepSeek Web, Gemini Web, vLLM, LiteLLM, Ollama) into a full Windows automation agent using plain JSON tool calling (no native function calling required).

### Launch WebAPI Control Panel

```bash
agent2win --webapi
```

### Features:
1. **Interactive Settings GUI**: Configure API Base URL, API Key, Model dropdown (with auto `/models` discovery), timeout settings, and step limits.
2. **Allowed Folders Containment**: Restrict file tools strictly to specified directories with canonical path resolution.
3. **Encrypted Storage**: API keys are encrypted at rest using native Windows DPAPI (`CryptProtectData`).
4. **OpenAI-Compatible Endpoints**:
   - `POST /v1/chat/completions` — Standard Chat Completion endpoint executing autonomous multi-step agent loops.
   - `POST /v1/responses` — Unified response format endpoint.
   - `GET /v1/models` — Proxied model listing.
   - `GET /api/webapi/status`, `POST /api/webapi/start`, `POST /api/webapi/stop` — Runtime lifecycle control.

---

## 🛠️ CLI Options

| Option | Description |
|---|---|
| `--webapi` | Open WebAPI Agent GUI to configure & connect OpenAI-compatible LLMs |
| `--port <PORT>` | Server port (Default: `7770`) |
| `--host <IP>` | Bind IP address (Default: `0.0.0.0`) |
| `--key <SECRET>` | Set Bearer token for API authentication |
| `--tunnel <PROVIDER>` | Tunnel provider (`cloudflared` or `ngrok`, default: `cloudflared`) |
| `--no-tunnel` | Local-only mode (disables public tunnel) |
| `--no-tray` | Disable Windows system tray icon |
| `--unrestricted` | Disable action approval prompts (⚠️ use carefully) |
| `--settings` | Open graphical configuration GUI |

---

## ⚠️ Advanced / High Risk: Unrestricted Mode

For automated benchmarks and continuous integration pipelines where interactive desktop approval dialogs are not possible:

```bash
agent2win --key YOUR_STRONG_RANDOM_API_KEY --unrestricted
```

> 🚨 **Security Notice:** In unrestricted mode, all valid command execution, file modifications, and OS actions are executed without confirmation prompts. Never run unrestricted mode on public networks without an API key.

---

## 📡 API Reference Overview

Full protocol specifications available in [AGENT_PROTOCOL.md](https://github.com/harikasinkaya/agent2win/blob/main/AGENT_PROTOCOL.md).

### 🖥️ Virtual Desktops (Background Mode)
- `GET /api/desktops` — List all virtual desktops.
- `POST /api/desktops/setup` — One-click create agent virtual desktop.
- `POST /api/desktops/switch_agent` — Shift active view to agent desktop.
- `POST /api/desktops/switch_user` — Switch active view back to user primary desktop.
- `POST /api/desktops/create` — Create virtual desktop `{"name": "Agent"}`.
- `POST /api/desktops/switch` — Switch desktop `{"index": 2}`.
- `POST /api/desktops/remove` — Remove desktop `{"index": 2}`.

### 📸 Screen & Windows
- `GET /api/screen` — Full desktop screenshot (Base64 JPEG).
- `GET /api/screen/info` — Monitor resolutions and coordinates.
- `GET /api/windows` — List active windows with HWND handles, titles, and processes.
- `GET /api/windows/foreground` — Get active foreground window.
- `POST /api/windows/screenshot` — Capture specific window by `hwnd`.
- `POST /api/windows/focus` — Bring window to foreground `{"hwnd": 12345}`.
- `POST /api/windows/close` — Close window `{"hwnd": 12345}`.

### 🖱️ Mouse & Keyboard
- `POST /api/mouse/click` — `{"x": 500, "y": 300, "button": "left"}`
- `POST /api/mouse/move` — `{"x": 500, "y": 300}`
- `POST /api/mouse/scroll` — `{"clicks": -5}`
- `POST /api/keyboard/type` — `{"text": "Hello World", "unicode": true}`
- `POST /api/keyboard/press` — `{"key": "enter"}`
- `POST /api/keyboard/hotkey` — `{"keys": ["ctrl", "c"]}`

### 💻 Shell & Filesystem
- `POST /api/command` — `{"cmd": "whoami", "timeout": 15}` (persistent server: `{"cmd": "npm start", "background": true}`)
- `GET /api/files/list?path=C:\Users` — List directory contents.
- `GET /api/files/read?path=C:\test.txt` — Read text file.
- `POST /api/files/write` — Write file `{"path": "C:\\test.txt", "content": "..."}`.
- `POST /api/files/mkdir` — Create directory `{"path": "C:\\folder"}`.
- `POST /api/files/delete` — Delete file or directory `{"path": "C:\\test.txt"}`.
- `GET /api/files/drives` — List available drive letters and free space.
- `GET /api/files/search?dir=C:\&pattern=*.txt` — Search files matching pattern.

### 🔊 Audio & System
- `GET /api/audio/volume` — Get volume level `{"level": 50, "muted": false}`.
- `POST /api/audio/volume` — Set volume `{"level": 50}`.
- `POST /api/audio/mute` / `POST /api/audio/unmute` — Mute/unmute master audio.
- `GET /api/audio/devices` — List playback and recording audio devices (`active`, `disabled`, `unplugged`, `not_present`).
- `GET /api/services?filter=spooler` — List Windows services.
- `GET /api/clipboard` / `POST /api/clipboard` — Read/write clipboard.

---

## 🔧 Development Installation

To install from source for development:

```bash
git clone https://github.com/harikasinkaya/agent2win.git
cd agent2win
pip install -e .
```

---

## 📄 License

Distributed under the MIT License. See [LICENSE](https://github.com/harikasinkaya/agent2win/blob/main/LICENSE) for details.
