Sky Windows Remote Executor

English | 简体中文

Sky Windows Remote Executor is a Windows-hosted FastAPI + MCP remote execution service for AI agents, automation scripts, remote maintenance, and local agent workflows.

It is not a thin SSH wrapper. It is a resident HTTP/MCP service with a Web UI, REST API, MCP tools, task logs, audit events, and transfer tickets for large files. By default it binds to 127.0.0.1, which makes it suitable for local use or trusted tunnels first.

Core Capabilities

• Web UI: inspect tasks, logs, configuration, file transfers, audit events, and service status.
• Command execution: run Python scripts, PowerShell commands, CMD commands, and Python snippets synchronously or asynchronously.
• MCP integration: expose tools through /mcp for Codex, Claude Desktop, or any MCP-compatible client.
• File operations: list directories, read/write files, search content, apply precise patches, upload, download, batch-download, and package folders as zip files.
• Windows administration: manage processes, services, registry values, scheduled tasks, network checks, event logs, notifications, and workstation lock.
• Desktop helpers: screenshot capture, clipboard read/write, and Windows Toast notifications.
• Operations: health checks, configuration read/update, log cleanup, task cleanup, and audit queries.
• Large file transfer: MCP returns short-lived transfer_reference objects while bytes move through one-shot REST URLs.

Safety First

This service can execute commands, write files, edit the registry, kill processes, manage services, and interact with the active Windows desktop. Treat it as a high-privilege remote control endpoint.

The default configuration binds to 127.0.0.1. If you expose it to other machines, place it behind a trusted firewall, VPN, SSH tunnel, or reverse proxy, and read SECURITY.md before deployment.

This project currently does not include built-in multi-user authentication, role-based authorization, or public internet hardening. Do not expose the port directly to the public internet.

Quick Start

python -m venv venv
.\venv\Scripts\python.exe -m pip install -r requirements.txt
.\venv\Scripts\python.exe -u windows_remote_executor.py

Open the Web UI:

http://localhost:8765

MCP endpoint:

http://localhost:8765/mcp

Windows Batch Helpers

| Script | Purpose | | --- | --- | | start-dev.bat | Run in the foreground and use repo-local .wre-data as the runtime data directory. | | start-silent.bat | Launch silently with pythonw. | | start-service.bat | Start the installed Windows service, or fall back to foreground mode when the service is not installed. | | install-service.bat | Install as a Windows service with NSSM. | | uninstall-service.bat | Remove the NSSM service. |

NSSM is not vendored. Install NSSM separately and place nssm.exe on PATH, or copy it next to the scripts before running install-service.bat.

Configuration

Configure the service with environment variables:

| Variable | Default | Description | | --- | --- | --- | | WRE_APP_NAME | Sky Windows Remote Executor | Web UI and display name. | | WRE_SERVICE_NAME | SkyWindowsRemoteExecutor | Windows service name. | | WRE_HOST | 127.0.0.1 | Uvicorn bind host. | | WRE_PORT | 8765 | HTTP/MCP port. | | WRE_DATA_DIR | %ProgramData%\SkyWindowsRemoteExecutor | Runtime data root. | | WRE_LOG_DIR | %WRE_DATA_DIR%\logs | Task and service logs. | | WRE_UPLOAD_DIR | %WRE_DATA_DIR%\uploads | Default upload directory. | | WRE_TEMP_DIR | %WRE_DATA_DIR%\temp | Temporary zip and transfer files. | | WRE_LOG_RETENTION_DAYS | 7 | Task log retention in days. | | WRE_AUTOSTART_TASK_NAME | SkyWindowsRemoteExecutorAutoStart | Scheduled task name for autostart. |

Example:

$env:WRE_HOST = "0.0.0.0"
$env:WRE_DATA_DIR = "D:\WindowsRemoteExecutor"
.\venv\Scripts\python.exe -u windows_remote_executor.py

REST API Coverage

Configuration, Health, and Maintenance

| Endpoint | Purpose | | --- | --- | | GET /health | Health check with service status, task count, and basic information. | | GET /config | Read log directory, upload directory, and log retention settings. | | POST /config | Update runtime-adjustable configuration. | | POST /config/cleanup-now | Manually clean expired task logs. | | GET /audit | Query audit events. |

Tasks and Command Execution

| Endpoint | Purpose | | --- | --- | | POST /run | Run a Python script in the background and return a task_id. | | POST /run-sync | Run a script synchronously and return stdout, stderr, and exit code. | | POST /powershell | Run a PowerShell command in the background. | | POST /powershell-sync | Run a PowerShell command synchronously. | | POST /stop/{task_id} | Stop a background task. | | GET /status/{task_id} | Query task status. | | GET /log/{task_id} | Read task logs with an optional line limit. | | GET /tasks | List tasks. | | POST /tasks/clear-finished | Clear finished task records. |

Files and Transfers

| Endpoint | Purpose | | --- | --- | | POST /upload | Upload one file to a target path. | | POST /batch/upload | Upload multiple files. | | POST /download | Download one file. | | POST /list | List directory entries with glob support. | | POST /file/read | Read file content, including text encodings and binary base64. | | POST /file/write | Write or append file content, with Python syntax check feedback for .py files. | | POST /file/search | Search file content. | | POST /file/request-download | Create a short-lived download ticket. | | GET /file/transfer/{ticket_id} | Stream a file authorized by a download ticket. | | POST /file/request-upload | Create a short-lived upload ticket. | | POST /file/transfer/{ticket_id} | Upload a file authorized by an upload ticket. |

Windows System Administration

| Endpoint | Purpose | | --- | --- | | POST /process/list | List processes with filtering, sorting, and limit support. | | POST /process/kill | Kill a process by PID or process name. | | POST /reg/read | Read a Windows registry value. | | POST /reg/write | Write a Windows registry value. | | POST /service/list | List Windows services. | | POST /service/start-svc | Start a Windows service. | | POST /service/stop-svc | Stop a Windows service. | | POST /service/restart | Restart a Windows service. | | POST /service/stop | Stop the current remote executor service process. | | GET /service/info | Inspect executor service information, PID, uptime, task counts, and log settings. | | GET /service/autostart | Inspect autostart state. | | POST /service/autostart | Enable or disable autostart. | | POST /task/list | List Windows scheduled tasks. | | POST /task/create | Create a Windows scheduled task. | | POST /task/delete | Delete a Windows scheduled task. |

Network, Desktop, and Events

| Endpoint | Purpose | | --- | --- | | POST /net/scrape | Fetch a web page content snippet. | | POST /net/ping | Ping a host. | | POST /net/port-check | Check whether a host port is reachable. | | POST /net/connections | List network connections. | | GET /clipboard | Read clipboard text. | | POST /clipboard | Write clipboard text. | | POST /notification | Show a Windows Toast notification. | | POST /lock-screen | Lock the Windows workstation. | | POST /event-log | Query Windows event logs. |

Realtime Channels and Pages

| Endpoint | Purpose | | --- | --- | | POST /mcp | MCP JSON-RPC entrypoint. | | GET / | Web UI home page. | | WebSocket /ws/log/{ws_task_id} | Subscribe to realtime logs for one task. | | WebSocket /ws/all | Subscribe to all task status updates. | | WebSocket /ws/audit | Subscribe to audit events. |

MCP Tool Coverage

MCP clients use tools/list to retrieve the full schema and tools/call to invoke a tool. See docs/mcp-guide.md and examples/codex-mcp-config.json for examples.

Commands and Long-Running Tasks

| Tool | Purpose | | --- | --- | | run_command | Run a PowerShell, CMD, or Python command synchronously and return stdout, stderr, and returncode. | | start_long_task | Start a background task for long-running scripts. | | get_task_status | Query background task status. | | get_task_log | Read background task logs. | | run_powershell_long | Run a long-running PowerShell command. | | stop_task | Stop a background task. | | list_tasks | List tasks. | | clear_finished_tasks | Clear finished task records. |

Files, Search, and Transfer

| Tool | Purpose | | --- | --- | | fs_read | Read a file; small files are returned inline, large files return a download ticket. | | fs_write | Write or append a file; small content is written inline, large content returns an upload ticket. | | fs_diff | Show the Git working tree diff for a file. | | fs_list | List a directory with glob support. | | content_search | Search content, preferring ripgrep and falling back to Python. | | patch_file | Replace exact old/new strings, with optional backup and Python syntax checks. | | upload_file | Upload one file with inline base64 or large-file ticket mode. | | download_file | Download one file with inline base64 or large-file ticket mode. | | batch_upload | Upload multiple files. | | batch_download | Package multiple remote files into a zip and return a download reference. | | download_folder | Package a remote folder into a zip using glob and recursive options. |

Windows System Administration

| Tool | Purpose | | --- | --- | | process_list | List processes. | | process_kill | Kill processes by PID or name. | | service_list | List Windows services. | | service_start | Start a service. | | service_stop | Stop a service. | | service_restart | Restart a service. | | get_service_info | Get executor service information. | | set_autostart | Configure executor autostart. | | reg_read | Read a registry value. | | reg_write | Write a registry value. | | scheduled_task_list | List scheduled tasks. | | create_scheduled_task | Create a scheduled task. | | delete_scheduled_task | Delete a scheduled task. |

Network, Desktop, and Diagnostics

| Tool | Purpose | | --- | --- | | screenshot | Capture the current Windows desktop, either saved to a file or returned as base64. | | clipboard | Read or set clipboard text. | | system_info | Return OS, hostname, process ID, service version, and related information. | | net_ping | Ping a host. | | net_port_check | Check host port connectivity. | | net_connections | List network connections. | | send_notification | Send a Windows Toast notification. | | lock_screen | Lock the Windows workstation. | | get_event_log | Query Windows event logs. | | get_audit_log | Query executor audit logs. | | health_check | Run a health check. | | get_config | Read executor configuration. | | update_config | Update executor configuration. | | cleanup_logs | Clean expired logs. | | git_commit | Commit current changes in a target Git repository. |

Large File Transfer Model

MCP is a control plane, not an ideal channel for large byte streams. This project uses a two-step transfer model for large files:

1. The MCP tool returns a transfer_reference with a one-shot download_url or upload_url.
2. The client transfers the real bytes through a normal HTTP GET or multipart POST request.

Transfer tickets are short-lived and single-use by default. This keeps MCP calls small while still allowing browsers or scripts to stream zip archives, model files, video assets, and other large artifacts.

Development

.\venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\venv\Scripts\python.exe -m unittest discover -s tests -v

License

MIT. See LICENSE.