# Sky Windows Remote Executor

[English](README.md) | [简体中文](README.zh-CN.md)

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](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

```powershell
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:

```text
http://localhost:8765
```

MCP endpoint:

```text
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:

```powershell
$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](docs/mcp-guide.md) and [examples/codex-mcp-config.json](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

```powershell
.\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](LICENSE).