agent2win 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent2win-1.0.0/LICENSE +21 -0
- agent2win-1.0.0/PKG-INFO +204 -0
- agent2win-1.0.0/README.md +169 -0
- agent2win-1.0.0/agent2win.egg-info/PKG-INFO +204 -0
- agent2win-1.0.0/agent2win.egg-info/SOURCES.txt +32 -0
- agent2win-1.0.0/agent2win.egg-info/dependency_links.txt +1 -0
- agent2win-1.0.0/agent2win.egg-info/entry_points.txt +2 -0
- agent2win-1.0.0/agent2win.egg-info/requires.txt +13 -0
- agent2win-1.0.0/agent2win.egg-info/top_level.txt +1 -0
- agent2win-1.0.0/pyproject.toml +51 -0
- agent2win-1.0.0/setup.cfg +4 -0
- agent2win-1.0.0/src/__init__.py +3 -0
- agent2win-1.0.0/src/audio.py +160 -0
- agent2win-1.0.0/src/cli.py +113 -0
- agent2win-1.0.0/src/clipboard.py +90 -0
- agent2win-1.0.0/src/commands.py +89 -0
- agent2win-1.0.0/src/config.py +64 -0
- agent2win-1.0.0/src/environment.py +220 -0
- agent2win-1.0.0/src/filesystem.py +197 -0
- agent2win-1.0.0/src/gui.py +141 -0
- agent2win-1.0.0/src/input_control.py +155 -0
- agent2win-1.0.0/src/logger.py +41 -0
- agent2win-1.0.0/src/network.py +199 -0
- agent2win-1.0.0/src/notifications.py +207 -0
- agent2win-1.0.0/src/processes.py +144 -0
- agent2win-1.0.0/src/registry.py +160 -0
- agent2win-1.0.0/src/screen.py +94 -0
- agent2win-1.0.0/src/server.py +1061 -0
- agent2win-1.0.0/src/services.py +124 -0
- agent2win-1.0.0/src/system_power.py +142 -0
- agent2win-1.0.0/src/tray.py +111 -0
- agent2win-1.0.0/src/tunnel.py +207 -0
- agent2win-1.0.0/src/virtual_desktop.py +232 -0
- agent2win-1.0.0/src/window_manager.py +313 -0
agent2win-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arena AI Community
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
agent2win-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent2win
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Universal Bridge Between Web/Cloud AI Agents (ChatGPT, Gemini, Grok, Claude) & Windows OS
|
|
5
|
+
Author: agent2win Developers
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/yourusername/agent2win
|
|
8
|
+
Project-URL: Documentation, https://github.com/yourusername/agent2win#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/yourusername/agent2win.git
|
|
10
|
+
Project-URL: Issues, https://github.com/yourusername/agent2win/issues
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
18
|
+
Classifier: Topic :: System :: Systems Administration
|
|
19
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
24
|
+
Requires-Dist: Pillow>=10.0.0
|
|
25
|
+
Requires-Dist: mss>=9.0.0
|
|
26
|
+
Requires-Dist: pyautogui>=0.9.54
|
|
27
|
+
Requires-Dist: pyperclip>=1.8.0
|
|
28
|
+
Requires-Dist: psutil>=5.9.0
|
|
29
|
+
Requires-Dist: pycaw>=20230407; platform_system == "Windows"
|
|
30
|
+
Requires-Dist: comtypes>=1.4.1; platform_system == "Windows"
|
|
31
|
+
Requires-Dist: pyvda>=1.0.0; platform_system == "Windows"
|
|
32
|
+
Requires-Dist: pystray>=0.19.0; platform_system == "Windows"
|
|
33
|
+
Requires-Dist: win10toast>=0.9; platform_system == "Windows"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# 🚀 agent2win
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
|
|
40
|
+
### Universal Bridge Between Web / Cloud AI Agents & Windows OS
|
|
41
|
+
|
|
42
|
+
**Control your Windows PC or Server directly from web-based AI platforms like ChatGPT, Gemini, Grok, Claude, or custom cloud agents.**
|
|
43
|
+
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
[](https://python.org)
|
|
46
|
+
[](https://microsoft.com/windows)
|
|
47
|
+
[](#-api-reference-overview)
|
|
48
|
+
|
|
49
|
+
</div>
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
> 💡 **Turn Any Web AI Into a Windows Agent:**
|
|
54
|
+
> Any AI model or platform with web/API browsing capabilities (**ChatGPT / Custom GPTs**, **Gemini**, **Grok**, **Claude**, **OpenAI Assistants**, **LangChain**, **CrewAI**) can be transformed into an autonomous computer-use agent to control your local Windows PC or remote Windows Server via secure REST / WebSocket endpoints.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 📖 Overview
|
|
59
|
+
|
|
60
|
+
**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.
|
|
61
|
+
|
|
62
|
+
Whether you are building custom autonomous agents or connecting conversational web AIs (chatgpt.com, gemini.google.com, grok.com) via Custom Actions / API tools, **agent2win** provides full control over your OS environment.
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
66
|
+
│ Web & Cloud AI Ecosystem │
|
|
67
|
+
│ • chatgpt.com (Custom GPTs / Actions) • gemini.google.com │
|
|
68
|
+
│ • grok.com / xAI • claude.ai / Anthropic │
|
|
69
|
+
│ • Autonomous Frameworks (LangChain, CrewAI, AutoGen, AutoGPT) │
|
|
70
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
71
|
+
│ HTTPS / WSS (API Key Auth)
|
|
72
|
+
▼
|
|
73
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
74
|
+
│ Cloudflare / ngrok Public Tunnel (Zero Port-Forwarding) │
|
|
75
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
76
|
+
│
|
|
77
|
+
▼
|
|
78
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
79
|
+
│ agent2win Server (:7770) │
|
|
80
|
+
├─────────────────────────────────┬────────────────────────────────┤
|
|
81
|
+
│ • Screen & Window Capture │ • Mouse & Keyboard Emulation │
|
|
82
|
+
│ • Shell & Command Runner │ • Virtual Desktop Isolation │
|
|
83
|
+
│ • Filesystem & Registry │ • Process & Service Manager │
|
|
84
|
+
│ • Clipboard & Audio Controls │ • Security & Approval Layer │
|
|
85
|
+
└─────────────────────────────────┴────────────────────────────────┘
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## ✨ Key Features
|
|
91
|
+
|
|
92
|
+
- 🌐 **Web AI Compatibility**: Turn web-based models (**ChatGPT Actions**, **Gemini**, **Grok**, **Claude**) into remote operators for your Windows machines.
|
|
93
|
+
- ⚡ **Zero-Config Public Tunnel**: Instant public HTTPS endpoint generated automatically using Cloudflare Tunnel (`cloudflared`) or `ngrok`. No static IP or port forwarding required.
|
|
94
|
+
- 🖥️ **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.
|
|
95
|
+
- 📸 **Vision & Window Capture**: Full display screenshots or targeted window-handle (`hwnd`) captures in base64 format for visual reasoning.
|
|
96
|
+
- 🖱️ **Hardware Input Emulation**: Mouse click, drag, scroll, and keyboard typing with complete Unicode / international character support.
|
|
97
|
+
- 💻 **OS & System Administration**: Run PowerShell/CMD scripts, manage filesystem (read/write/search), list/kill processes, inspect Windows Services, and edit Registry keys.
|
|
98
|
+
- 🔒 **Comprehensive Security Layer**: Token authentication (`Bearer`), real-time desktop approval prompts for risky commands, system tray killswitch, and audit logging.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## ⚡ Quick Start
|
|
103
|
+
|
|
104
|
+
### 1. Install
|
|
105
|
+
|
|
106
|
+
Clone repository and install dependencies:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
git clone https://github.com/yourusername/agent2win.git
|
|
110
|
+
cd agent2win
|
|
111
|
+
pip install -r requirements.txt
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
*Or double-click `install.bat` on Windows.*
|
|
115
|
+
|
|
116
|
+
### 2. Run Server
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
python main.py
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
*Or double-click `start.bat`.*
|
|
123
|
+
|
|
124
|
+
### 3. Connect Any AI Agent
|
|
125
|
+
|
|
126
|
+
The console displays your live public HTTPS tunnel:
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
🌐 Tunnel: https://xxxx-xxxx-xxxx.trycloudflare.com
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Connect your AI agent (e.g. ChatGPT Custom Action schema, LangChain tool, or web agent) using this URL.
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 🤖 Using With Web AIs (ChatGPT, Gemini, Grok, Claude)
|
|
137
|
+
|
|
138
|
+
### ChatGPT Custom GPTs / Actions
|
|
139
|
+
1. Open ChatGPT -> Create a GPT -> Configure -> **Add Action**.
|
|
140
|
+
2. Set Server URL to your tunnel address (`https://xxxx.trycloudflare.com`).
|
|
141
|
+
3. Set Authentication to **API Key** (Bearer token) if configured.
|
|
142
|
+
4. Import endpoints from `AGENT_PROTOCOL.md` to let ChatGPT inspect your screen, run commands, and click UI elements.
|
|
143
|
+
|
|
144
|
+
### Gemini, Grok & Cloud Agents
|
|
145
|
+
Pass the public tunnel URL and API endpoints into your agent execution loop. The agent can take screenshots (`/api/screen`), process images with vision models, and issue input commands (`/api/mouse/click`, `/api/keyboard/type`).
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## 🛠️ CLI Options
|
|
150
|
+
|
|
151
|
+
| Flag | Description |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `--port <PORT>` | Server port (Default: `7770`) |
|
|
154
|
+
| `--host <IP>` | Bind IP address (Default: `0.0.0.0`) |
|
|
155
|
+
| `--key <SECRET>` | Set Bearer token for API authentication |
|
|
156
|
+
| `--unrestricted` | Disable action approval prompts (⚠️ use carefully) |
|
|
157
|
+
| `--tunnel <PROVIDER>` | Tunnel provider (`cloudflared` or `ngrok`) |
|
|
158
|
+
| `--no-tunnel` | Local-only mode (disables tunnels) |
|
|
159
|
+
| `--no-tray` | Disable Windows system tray icon |
|
|
160
|
+
| `--settings` | Open graphical configuration GUI |
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## 📡 API Reference Overview
|
|
165
|
+
|
|
166
|
+
Full protocol specifications available in [AGENT_PROTOCOL.md](AGENT_PROTOCOL.md).
|
|
167
|
+
|
|
168
|
+
### 🖥️ Virtual Desktops (Background Mode)
|
|
169
|
+
- `POST /api/desktops/setup` — Create agent virtual desktop.
|
|
170
|
+
- `POST /api/desktops/switch_agent` — Switch active view to agent desktop.
|
|
171
|
+
- `POST /api/desktops/switch_user` — Switch active view back to user desktop.
|
|
172
|
+
|
|
173
|
+
### 📸 Screen & Windows
|
|
174
|
+
- `GET /api/screen` — Full desktop screenshot (Base64 JPEG).
|
|
175
|
+
- `GET /api/windows` — List active windows with handles (`hwnd`) and coordinates.
|
|
176
|
+
- `POST /api/windows/screenshot` — Capture specific window by `hwnd`.
|
|
177
|
+
- `POST /api/windows/focus` — Bring window to foreground.
|
|
178
|
+
|
|
179
|
+
### 🖱️ Mouse & Keyboard
|
|
180
|
+
- `POST /api/mouse/click` — `{"x": 500, "y": 300, "button": "left"}`
|
|
181
|
+
- `POST /api/mouse/scroll` — `{"clicks": -5}`
|
|
182
|
+
- `POST /api/keyboard/type` — `{"text": "Hello World", "unicode": true}`
|
|
183
|
+
- `POST /api/keyboard/hotkey` — `{"keys": ["ctrl", "c"]}`
|
|
184
|
+
|
|
185
|
+
### 💻 Shell & Filesystem
|
|
186
|
+
- `POST /api/command` — `{"cmd": "dir C:\\", "timeout": 10}`
|
|
187
|
+
- `GET /api/fs/list?path=C:\` — List directory contents.
|
|
188
|
+
- `POST /api/fs/read` — Read file contents.
|
|
189
|
+
- `POST /api/fs/write` — Write file contents.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## 🔒 Security & Approvals
|
|
194
|
+
|
|
195
|
+
- **Safe Mode (Default)**: Critical actions (destructive shell commands, file deletions, registry writes, system reboot/shutdown) trigger desktop approval prompts.
|
|
196
|
+
- **Unrestricted Mode (`--unrestricted`)**: Disables interactive confirmation for headless/autonomous agents.
|
|
197
|
+
- **Audit Logs**: All executions recorded in `logs/audit.log`.
|
|
198
|
+
- **Tray Killswitch**: Pause or stop the server directly from the Windows taskbar.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## 📄 License
|
|
203
|
+
|
|
204
|
+
Distributed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# 🚀 agent2win
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
### Universal Bridge Between Web / Cloud AI Agents & Windows OS
|
|
6
|
+
|
|
7
|
+
**Control your Windows PC or Server directly from web-based AI platforms like ChatGPT, Gemini, Grok, Claude, or custom cloud agents.**
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://python.org)
|
|
11
|
+
[](https://microsoft.com/windows)
|
|
12
|
+
[](#-api-reference-overview)
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
> 💡 **Turn Any Web AI Into a Windows Agent:**
|
|
19
|
+
> Any AI model or platform with web/API browsing capabilities (**ChatGPT / Custom GPTs**, **Gemini**, **Grok**, **Claude**, **OpenAI Assistants**, **LangChain**, **CrewAI**) can be transformed into an autonomous computer-use agent to control your local Windows PC or remote Windows Server via secure REST / WebSocket endpoints.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 📖 Overview
|
|
24
|
+
|
|
25
|
+
**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.
|
|
26
|
+
|
|
27
|
+
Whether you are building custom autonomous agents or connecting conversational web AIs (chatgpt.com, gemini.google.com, grok.com) via Custom Actions / API tools, **agent2win** provides full control over your OS environment.
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
31
|
+
│ Web & Cloud AI Ecosystem │
|
|
32
|
+
│ • chatgpt.com (Custom GPTs / Actions) • gemini.google.com │
|
|
33
|
+
│ • grok.com / xAI • claude.ai / Anthropic │
|
|
34
|
+
│ • Autonomous Frameworks (LangChain, CrewAI, AutoGen, AutoGPT) │
|
|
35
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
36
|
+
│ HTTPS / WSS (API Key Auth)
|
|
37
|
+
▼
|
|
38
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
39
|
+
│ Cloudflare / ngrok Public Tunnel (Zero Port-Forwarding) │
|
|
40
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
41
|
+
│
|
|
42
|
+
▼
|
|
43
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
44
|
+
│ agent2win Server (:7770) │
|
|
45
|
+
├─────────────────────────────────┬────────────────────────────────┤
|
|
46
|
+
│ • Screen & Window Capture │ • Mouse & Keyboard Emulation │
|
|
47
|
+
│ • Shell & Command Runner │ • Virtual Desktop Isolation │
|
|
48
|
+
│ • Filesystem & Registry │ • Process & Service Manager │
|
|
49
|
+
│ • Clipboard & Audio Controls │ • Security & Approval Layer │
|
|
50
|
+
└─────────────────────────────────┴────────────────────────────────┘
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## ✨ Key Features
|
|
56
|
+
|
|
57
|
+
- 🌐 **Web AI Compatibility**: Turn web-based models (**ChatGPT Actions**, **Gemini**, **Grok**, **Claude**) into remote operators for your Windows machines.
|
|
58
|
+
- ⚡ **Zero-Config Public Tunnel**: Instant public HTTPS endpoint generated automatically using Cloudflare Tunnel (`cloudflared`) or `ngrok`. No static IP or port forwarding required.
|
|
59
|
+
- 🖥️ **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.
|
|
60
|
+
- 📸 **Vision & Window Capture**: Full display screenshots or targeted window-handle (`hwnd`) captures in base64 format for visual reasoning.
|
|
61
|
+
- 🖱️ **Hardware Input Emulation**: Mouse click, drag, scroll, and keyboard typing with complete Unicode / international character support.
|
|
62
|
+
- 💻 **OS & System Administration**: Run PowerShell/CMD scripts, manage filesystem (read/write/search), list/kill processes, inspect Windows Services, and edit Registry keys.
|
|
63
|
+
- 🔒 **Comprehensive Security Layer**: Token authentication (`Bearer`), real-time desktop approval prompts for risky commands, system tray killswitch, and audit logging.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## ⚡ Quick Start
|
|
68
|
+
|
|
69
|
+
### 1. Install
|
|
70
|
+
|
|
71
|
+
Clone repository and install dependencies:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
git clone https://github.com/yourusername/agent2win.git
|
|
75
|
+
cd agent2win
|
|
76
|
+
pip install -r requirements.txt
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
*Or double-click `install.bat` on Windows.*
|
|
80
|
+
|
|
81
|
+
### 2. Run Server
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
python main.py
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
*Or double-click `start.bat`.*
|
|
88
|
+
|
|
89
|
+
### 3. Connect Any AI Agent
|
|
90
|
+
|
|
91
|
+
The console displays your live public HTTPS tunnel:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
🌐 Tunnel: https://xxxx-xxxx-xxxx.trycloudflare.com
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Connect your AI agent (e.g. ChatGPT Custom Action schema, LangChain tool, or web agent) using this URL.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 🤖 Using With Web AIs (ChatGPT, Gemini, Grok, Claude)
|
|
102
|
+
|
|
103
|
+
### ChatGPT Custom GPTs / Actions
|
|
104
|
+
1. Open ChatGPT -> Create a GPT -> Configure -> **Add Action**.
|
|
105
|
+
2. Set Server URL to your tunnel address (`https://xxxx.trycloudflare.com`).
|
|
106
|
+
3. Set Authentication to **API Key** (Bearer token) if configured.
|
|
107
|
+
4. Import endpoints from `AGENT_PROTOCOL.md` to let ChatGPT inspect your screen, run commands, and click UI elements.
|
|
108
|
+
|
|
109
|
+
### Gemini, Grok & Cloud Agents
|
|
110
|
+
Pass the public tunnel URL and API endpoints into your agent execution loop. The agent can take screenshots (`/api/screen`), process images with vision models, and issue input commands (`/api/mouse/click`, `/api/keyboard/type`).
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 🛠️ CLI Options
|
|
115
|
+
|
|
116
|
+
| Flag | Description |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `--port <PORT>` | Server port (Default: `7770`) |
|
|
119
|
+
| `--host <IP>` | Bind IP address (Default: `0.0.0.0`) |
|
|
120
|
+
| `--key <SECRET>` | Set Bearer token for API authentication |
|
|
121
|
+
| `--unrestricted` | Disable action approval prompts (⚠️ use carefully) |
|
|
122
|
+
| `--tunnel <PROVIDER>` | Tunnel provider (`cloudflared` or `ngrok`) |
|
|
123
|
+
| `--no-tunnel` | Local-only mode (disables tunnels) |
|
|
124
|
+
| `--no-tray` | Disable Windows system tray icon |
|
|
125
|
+
| `--settings` | Open graphical configuration GUI |
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## 📡 API Reference Overview
|
|
130
|
+
|
|
131
|
+
Full protocol specifications available in [AGENT_PROTOCOL.md](AGENT_PROTOCOL.md).
|
|
132
|
+
|
|
133
|
+
### 🖥️ Virtual Desktops (Background Mode)
|
|
134
|
+
- `POST /api/desktops/setup` — Create agent virtual desktop.
|
|
135
|
+
- `POST /api/desktops/switch_agent` — Switch active view to agent desktop.
|
|
136
|
+
- `POST /api/desktops/switch_user` — Switch active view back to user desktop.
|
|
137
|
+
|
|
138
|
+
### 📸 Screen & Windows
|
|
139
|
+
- `GET /api/screen` — Full desktop screenshot (Base64 JPEG).
|
|
140
|
+
- `GET /api/windows` — List active windows with handles (`hwnd`) and coordinates.
|
|
141
|
+
- `POST /api/windows/screenshot` — Capture specific window by `hwnd`.
|
|
142
|
+
- `POST /api/windows/focus` — Bring window to foreground.
|
|
143
|
+
|
|
144
|
+
### 🖱️ Mouse & Keyboard
|
|
145
|
+
- `POST /api/mouse/click` — `{"x": 500, "y": 300, "button": "left"}`
|
|
146
|
+
- `POST /api/mouse/scroll` — `{"clicks": -5}`
|
|
147
|
+
- `POST /api/keyboard/type` — `{"text": "Hello World", "unicode": true}`
|
|
148
|
+
- `POST /api/keyboard/hotkey` — `{"keys": ["ctrl", "c"]}`
|
|
149
|
+
|
|
150
|
+
### 💻 Shell & Filesystem
|
|
151
|
+
- `POST /api/command` — `{"cmd": "dir C:\\", "timeout": 10}`
|
|
152
|
+
- `GET /api/fs/list?path=C:\` — List directory contents.
|
|
153
|
+
- `POST /api/fs/read` — Read file contents.
|
|
154
|
+
- `POST /api/fs/write` — Write file contents.
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 🔒 Security & Approvals
|
|
159
|
+
|
|
160
|
+
- **Safe Mode (Default)**: Critical actions (destructive shell commands, file deletions, registry writes, system reboot/shutdown) trigger desktop approval prompts.
|
|
161
|
+
- **Unrestricted Mode (`--unrestricted`)**: Disables interactive confirmation for headless/autonomous agents.
|
|
162
|
+
- **Audit Logs**: All executions recorded in `logs/audit.log`.
|
|
163
|
+
- **Tray Killswitch**: Pause or stop the server directly from the Windows taskbar.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## 📄 License
|
|
168
|
+
|
|
169
|
+
Distributed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent2win
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Universal Bridge Between Web/Cloud AI Agents (ChatGPT, Gemini, Grok, Claude) & Windows OS
|
|
5
|
+
Author: agent2win Developers
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/yourusername/agent2win
|
|
8
|
+
Project-URL: Documentation, https://github.com/yourusername/agent2win#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/yourusername/agent2win.git
|
|
10
|
+
Project-URL: Issues, https://github.com/yourusername/agent2win/issues
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
18
|
+
Classifier: Topic :: System :: Systems Administration
|
|
19
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
24
|
+
Requires-Dist: Pillow>=10.0.0
|
|
25
|
+
Requires-Dist: mss>=9.0.0
|
|
26
|
+
Requires-Dist: pyautogui>=0.9.54
|
|
27
|
+
Requires-Dist: pyperclip>=1.8.0
|
|
28
|
+
Requires-Dist: psutil>=5.9.0
|
|
29
|
+
Requires-Dist: pycaw>=20230407; platform_system == "Windows"
|
|
30
|
+
Requires-Dist: comtypes>=1.4.1; platform_system == "Windows"
|
|
31
|
+
Requires-Dist: pyvda>=1.0.0; platform_system == "Windows"
|
|
32
|
+
Requires-Dist: pystray>=0.19.0; platform_system == "Windows"
|
|
33
|
+
Requires-Dist: win10toast>=0.9; platform_system == "Windows"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# 🚀 agent2win
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
|
|
40
|
+
### Universal Bridge Between Web / Cloud AI Agents & Windows OS
|
|
41
|
+
|
|
42
|
+
**Control your Windows PC or Server directly from web-based AI platforms like ChatGPT, Gemini, Grok, Claude, or custom cloud agents.**
|
|
43
|
+
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
[](https://python.org)
|
|
46
|
+
[](https://microsoft.com/windows)
|
|
47
|
+
[](#-api-reference-overview)
|
|
48
|
+
|
|
49
|
+
</div>
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
> 💡 **Turn Any Web AI Into a Windows Agent:**
|
|
54
|
+
> Any AI model or platform with web/API browsing capabilities (**ChatGPT / Custom GPTs**, **Gemini**, **Grok**, **Claude**, **OpenAI Assistants**, **LangChain**, **CrewAI**) can be transformed into an autonomous computer-use agent to control your local Windows PC or remote Windows Server via secure REST / WebSocket endpoints.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 📖 Overview
|
|
59
|
+
|
|
60
|
+
**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.
|
|
61
|
+
|
|
62
|
+
Whether you are building custom autonomous agents or connecting conversational web AIs (chatgpt.com, gemini.google.com, grok.com) via Custom Actions / API tools, **agent2win** provides full control over your OS environment.
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
66
|
+
│ Web & Cloud AI Ecosystem │
|
|
67
|
+
│ • chatgpt.com (Custom GPTs / Actions) • gemini.google.com │
|
|
68
|
+
│ • grok.com / xAI • claude.ai / Anthropic │
|
|
69
|
+
│ • Autonomous Frameworks (LangChain, CrewAI, AutoGen, AutoGPT) │
|
|
70
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
71
|
+
│ HTTPS / WSS (API Key Auth)
|
|
72
|
+
▼
|
|
73
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
74
|
+
│ Cloudflare / ngrok Public Tunnel (Zero Port-Forwarding) │
|
|
75
|
+
└─────────────────────────────────┬────────────────────────────────┘
|
|
76
|
+
│
|
|
77
|
+
▼
|
|
78
|
+
┌──────────────────────────────────────────────────────────────────┐
|
|
79
|
+
│ agent2win Server (:7770) │
|
|
80
|
+
├─────────────────────────────────┬────────────────────────────────┤
|
|
81
|
+
│ • Screen & Window Capture │ • Mouse & Keyboard Emulation │
|
|
82
|
+
│ • Shell & Command Runner │ • Virtual Desktop Isolation │
|
|
83
|
+
│ • Filesystem & Registry │ • Process & Service Manager │
|
|
84
|
+
│ • Clipboard & Audio Controls │ • Security & Approval Layer │
|
|
85
|
+
└─────────────────────────────────┴────────────────────────────────┘
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## ✨ Key Features
|
|
91
|
+
|
|
92
|
+
- 🌐 **Web AI Compatibility**: Turn web-based models (**ChatGPT Actions**, **Gemini**, **Grok**, **Claude**) into remote operators for your Windows machines.
|
|
93
|
+
- ⚡ **Zero-Config Public Tunnel**: Instant public HTTPS endpoint generated automatically using Cloudflare Tunnel (`cloudflared`) or `ngrok`. No static IP or port forwarding required.
|
|
94
|
+
- 🖥️ **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.
|
|
95
|
+
- 📸 **Vision & Window Capture**: Full display screenshots or targeted window-handle (`hwnd`) captures in base64 format for visual reasoning.
|
|
96
|
+
- 🖱️ **Hardware Input Emulation**: Mouse click, drag, scroll, and keyboard typing with complete Unicode / international character support.
|
|
97
|
+
- 💻 **OS & System Administration**: Run PowerShell/CMD scripts, manage filesystem (read/write/search), list/kill processes, inspect Windows Services, and edit Registry keys.
|
|
98
|
+
- 🔒 **Comprehensive Security Layer**: Token authentication (`Bearer`), real-time desktop approval prompts for risky commands, system tray killswitch, and audit logging.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## ⚡ Quick Start
|
|
103
|
+
|
|
104
|
+
### 1. Install
|
|
105
|
+
|
|
106
|
+
Clone repository and install dependencies:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
git clone https://github.com/yourusername/agent2win.git
|
|
110
|
+
cd agent2win
|
|
111
|
+
pip install -r requirements.txt
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
*Or double-click `install.bat` on Windows.*
|
|
115
|
+
|
|
116
|
+
### 2. Run Server
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
python main.py
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
*Or double-click `start.bat`.*
|
|
123
|
+
|
|
124
|
+
### 3. Connect Any AI Agent
|
|
125
|
+
|
|
126
|
+
The console displays your live public HTTPS tunnel:
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
🌐 Tunnel: https://xxxx-xxxx-xxxx.trycloudflare.com
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Connect your AI agent (e.g. ChatGPT Custom Action schema, LangChain tool, or web agent) using this URL.
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 🤖 Using With Web AIs (ChatGPT, Gemini, Grok, Claude)
|
|
137
|
+
|
|
138
|
+
### ChatGPT Custom GPTs / Actions
|
|
139
|
+
1. Open ChatGPT -> Create a GPT -> Configure -> **Add Action**.
|
|
140
|
+
2. Set Server URL to your tunnel address (`https://xxxx.trycloudflare.com`).
|
|
141
|
+
3. Set Authentication to **API Key** (Bearer token) if configured.
|
|
142
|
+
4. Import endpoints from `AGENT_PROTOCOL.md` to let ChatGPT inspect your screen, run commands, and click UI elements.
|
|
143
|
+
|
|
144
|
+
### Gemini, Grok & Cloud Agents
|
|
145
|
+
Pass the public tunnel URL and API endpoints into your agent execution loop. The agent can take screenshots (`/api/screen`), process images with vision models, and issue input commands (`/api/mouse/click`, `/api/keyboard/type`).
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## 🛠️ CLI Options
|
|
150
|
+
|
|
151
|
+
| Flag | Description |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `--port <PORT>` | Server port (Default: `7770`) |
|
|
154
|
+
| `--host <IP>` | Bind IP address (Default: `0.0.0.0`) |
|
|
155
|
+
| `--key <SECRET>` | Set Bearer token for API authentication |
|
|
156
|
+
| `--unrestricted` | Disable action approval prompts (⚠️ use carefully) |
|
|
157
|
+
| `--tunnel <PROVIDER>` | Tunnel provider (`cloudflared` or `ngrok`) |
|
|
158
|
+
| `--no-tunnel` | Local-only mode (disables tunnels) |
|
|
159
|
+
| `--no-tray` | Disable Windows system tray icon |
|
|
160
|
+
| `--settings` | Open graphical configuration GUI |
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## 📡 API Reference Overview
|
|
165
|
+
|
|
166
|
+
Full protocol specifications available in [AGENT_PROTOCOL.md](AGENT_PROTOCOL.md).
|
|
167
|
+
|
|
168
|
+
### 🖥️ Virtual Desktops (Background Mode)
|
|
169
|
+
- `POST /api/desktops/setup` — Create agent virtual desktop.
|
|
170
|
+
- `POST /api/desktops/switch_agent` — Switch active view to agent desktop.
|
|
171
|
+
- `POST /api/desktops/switch_user` — Switch active view back to user desktop.
|
|
172
|
+
|
|
173
|
+
### 📸 Screen & Windows
|
|
174
|
+
- `GET /api/screen` — Full desktop screenshot (Base64 JPEG).
|
|
175
|
+
- `GET /api/windows` — List active windows with handles (`hwnd`) and coordinates.
|
|
176
|
+
- `POST /api/windows/screenshot` — Capture specific window by `hwnd`.
|
|
177
|
+
- `POST /api/windows/focus` — Bring window to foreground.
|
|
178
|
+
|
|
179
|
+
### 🖱️ Mouse & Keyboard
|
|
180
|
+
- `POST /api/mouse/click` — `{"x": 500, "y": 300, "button": "left"}`
|
|
181
|
+
- `POST /api/mouse/scroll` — `{"clicks": -5}`
|
|
182
|
+
- `POST /api/keyboard/type` — `{"text": "Hello World", "unicode": true}`
|
|
183
|
+
- `POST /api/keyboard/hotkey` — `{"keys": ["ctrl", "c"]}`
|
|
184
|
+
|
|
185
|
+
### 💻 Shell & Filesystem
|
|
186
|
+
- `POST /api/command` — `{"cmd": "dir C:\\", "timeout": 10}`
|
|
187
|
+
- `GET /api/fs/list?path=C:\` — List directory contents.
|
|
188
|
+
- `POST /api/fs/read` — Read file contents.
|
|
189
|
+
- `POST /api/fs/write` — Write file contents.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## 🔒 Security & Approvals
|
|
194
|
+
|
|
195
|
+
- **Safe Mode (Default)**: Critical actions (destructive shell commands, file deletions, registry writes, system reboot/shutdown) trigger desktop approval prompts.
|
|
196
|
+
- **Unrestricted Mode (`--unrestricted`)**: Disables interactive confirmation for headless/autonomous agents.
|
|
197
|
+
- **Audit Logs**: All executions recorded in `logs/audit.log`.
|
|
198
|
+
- **Tray Killswitch**: Pause or stop the server directly from the Windows taskbar.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## 📄 License
|
|
203
|
+
|
|
204
|
+
Distributed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
agent2win.egg-info/PKG-INFO
|
|
5
|
+
agent2win.egg-info/SOURCES.txt
|
|
6
|
+
agent2win.egg-info/dependency_links.txt
|
|
7
|
+
agent2win.egg-info/entry_points.txt
|
|
8
|
+
agent2win.egg-info/requires.txt
|
|
9
|
+
agent2win.egg-info/top_level.txt
|
|
10
|
+
src/__init__.py
|
|
11
|
+
src/audio.py
|
|
12
|
+
src/cli.py
|
|
13
|
+
src/clipboard.py
|
|
14
|
+
src/commands.py
|
|
15
|
+
src/config.py
|
|
16
|
+
src/environment.py
|
|
17
|
+
src/filesystem.py
|
|
18
|
+
src/gui.py
|
|
19
|
+
src/input_control.py
|
|
20
|
+
src/logger.py
|
|
21
|
+
src/network.py
|
|
22
|
+
src/notifications.py
|
|
23
|
+
src/processes.py
|
|
24
|
+
src/registry.py
|
|
25
|
+
src/screen.py
|
|
26
|
+
src/server.py
|
|
27
|
+
src/services.py
|
|
28
|
+
src/system_power.py
|
|
29
|
+
src/tray.py
|
|
30
|
+
src/tunnel.py
|
|
31
|
+
src/virtual_desktop.py
|
|
32
|
+
src/window_manager.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
agent2win
|