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.