🚀 agent2win

💡 Turn Any Web AI / curl-Capable Agent Into a Windows Operator:
Any AI platform or model with HTTP/curl or web browsing capabilities (Arena.ai, ChatGPT / Custom Actions, Grok, Claude, OpenAI Assistants, LangChain, CrewAI) can execute native curl requests to interact with and control your Windows machine remotely via secure REST / WebSocket endpoints.

📖 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 OS.

┌──────────────────────────────────────────────────────────────────┐
│ 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    │
└─────────────────────────────────┴────────────────────────────────┘

                              │
                              ▼

┌──────────────────────────────────────────────────────────────────┐ │ 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**: Turn web-based models (**ChatGPT Actions**, **Gemini**, **Grok**, **Claude**) into remote operators for 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 hidden/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), list/kill processes, inspect Windows Services, and edit Registry keys.
- 🔒 **Comprehensive Security Layer**: Token authentication (`Bearer`), real-time desktop approval prompts for risky commands, system tray killswitch, and audit logging.

---

## ⚡ Quick Start

### 1. Install

Clone repository and install dependencies:

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

Or double-click install.bat on Windows.

2. Run Server

python main.py

Or double-click start.bat.

3. Connect Any AI Agent

The console displays your live public HTTPS tunnel:

🌐 Tunnel: https://xxxx-xxxx-xxxx.trycloudflare.com

Connect your AI agent (e.g. ChatGPT Custom Action schema, LangChain tool, or web agent) using this URL.

🤖 Using With Web AIs & 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:

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

Please inspect the system info, capture the screen, and follow my instructions to control my Windows machine.

⚡ Example curl Commands Executed by Agents (e.g. Arena.ai)

Agents running in terminal/bash environments can issue direct curl requests:

# 1. Get system info & active window
curl -X GET "https://xxxx.trycloudflare.com/api/info"

# 2. Capture desktop screen
curl -X GET "https://xxxx.trycloudflare.com/api/screen"

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

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

# 5. Run shell command
curl -X POST "https://xxxx.trycloudflare.com/api/command" \
     -H "Content-Type: application/json" \
     -d '{"cmd": "dir C:\\"}'

ChatGPT Custom GPTs / Actions

1. Open ChatGPT -> Create a GPT -> Configure -> Add Action.
2. Set Server URL to your tunnel address (https://xxxx.trycloudflare.com).
3. Set Authentication to API Key (Bearer token) if configured.
4. Import endpoints from AGENT_PROTOCOL.md to let ChatGPT inspect your screen, run commands, and click UI elements.

🛠️ CLI Options

📡 API Reference Overview

Full protocol specifications available in AGENT_PROTOCOL.md.

🖥️ Virtual Desktops (Background Mode)

• POST /api/desktops/setup — Create agent virtual desktop.
• POST /api/desktops/switch_agent — Switch active view to agent desktop.
• POST /api/desktops/switch_user — Switch active view back to user desktop.

📸 Screen & Windows

• GET /api/screen — Full desktop screenshot (Base64 JPEG).
• GET /api/windows — List active windows with handles (hwnd) and coordinates.
• POST /api/windows/screenshot — Capture specific window by hwnd.
• POST /api/windows/focus — Bring window to foreground.

🖱️ Mouse & Keyboard

• POST /api/mouse/click — {"x": 500, "y": 300, "button": "left"}
• POST /api/mouse/scroll — {"clicks": -5}
• POST /api/keyboard/type — {"text": "Hello World", "unicode": true}
• POST /api/keyboard/hotkey — {"keys": ["ctrl", "c"]}

💻 Shell & Filesystem

• POST /api/command — {"cmd": "dir C:\\", "timeout": 10}
• GET /api/fs/list?path=C:\ — List directory contents.
• POST /api/fs/read — Read file contents.
• POST /api/fs/write — Write file contents.

🔒 Security & Approvals

• Safe Mode (Default): Critical actions (destructive shell commands, file deletions, registry writes, system reboot/shutdown) trigger desktop approval prompts.
• Unrestricted Mode (--unrestricted): Disables interactive confirmation for headless/autonomous agents.
• Audit Logs: All executions recorded in logs/audit.log.
• Tray Killswitch: Pause or stop the server directly from the Windows taskbar.

📄 License

Distributed under the MIT License. See LICENSE for details.