🚀 agent2win

⚠️ 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

pip install agent2win

2. Run Server (Recommended Secure Public Tunnel)

agent2win --key YOUR_STRONG_RANDOM_API_KEY --tunnel cloudflared

The console displays your live public HTTPS tunnel:

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

Local-Only Usage (No Public Tunnel)

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:

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)

# 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

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

⚠️ Advanced / High Risk: Unrestricted Mode

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

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.

🖥️ 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:

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

📄 License

Distributed under the MIT License. See LICENSE for details.