agentwin 0.1.1

Agent-friendly Windows remote management CLI

agentwin

Agent-friendly Windows remote management CLI — a uv tool for AI agents to remotely manage Windows machines via WinRM or SSH.

---

English

What is agentwin?

agentwin is a command-line tool designed for AI agents (and humans) to interact with remote Windows devices. It supports both WinRM (NTLM) and SSH protocols, with automatic protocol detection, encrypted credential storage, and agent-friendly output formatting.

Installation

🎯 Recommended: install as an AI agent skill (npx skills add)

The agentwin skill (this repo's skills/agentwin/SKILL.md) is consumable by any agent in the open Vercel Skills ecosystem (Claude Code, OpenCode, Cursor, Codex, Antigravity, etc.) via the npx skills CLI:

# Install the agentwin skill into a specific agent
npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a claude-code

# Or install into ALL supported agents at once
npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a '*'

The npx skills tool is a Node.js package — it auto-downloads on first run, so no manual install is needed.

🤖 For AI agents: one-line install prompt

Copy-paste this to your AI agent (Claude, Cursor, etc.):

Please install the agentwin skill for me. Run this exact command and report the result: npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a '*' After it completes, verify with npx skills list | grep agentwin so I know it's active.

Alternative: uv tool install

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install agentwin
uv tool install agentwin

# Verify
agentwin --version

Run without installing: uvx

uvx is the Python equivalent of npx — it downloads, runs, and discards. Perfect for one-off commands or trying it out:

# Run any subcommand without globally installing
uvx agentwin health 10.0.0.20
uvx agentwin sysinfo --host <uuid>
uvx agentwin --help

# Always use the latest version
uvx --from agentwin agentwin --version

From source (contributors)

git clone https://github.com/xiaoka76/agentwin.git
cd agentwin
uv tool install -e .

Quick Start

# 1. Health check — scan ports and detect available protocols
agentwin health 10.0.0.20

# 2. Authenticate — save encrypted credentials
agentwin auth 10.0.0.20 --user Administrator --password "your_password"

#    Or specify auth method explicitly (default: port 5985→WinRM, port 22→SSH)
agentwin auth 10.0.0.20 --user Administrator --password "your_password" --method winrm-password
agentwin auth 10.0.0.20 --user Administrator --password "your_password" --port 2222 --method ssh-password
agentwin auth 10.0.0.20 --user Administrator --key ~/.ssh/id_rsa

# 3. List saved hosts
agentwin list

# 4. Execute a command (default: PowerShell)
agentwin execute --host a1b2c3d4 "Get-ChildItem C:\Users"
#    Use --cmd to run via cmd.exe instead
agentwin execute --host a1b2c3d4 --cmd "ipconfig /all"

# 5. Collect system information
agentwin sysinfo --host a1b2c3d4

Subcommands

Command	Description
health	Scan target host for open ports and protocols
auth	Authenticate and save encrypted credentials
execute	Run a single command (default: PowerShell, --cmd for cmd.exe)
script	Run a PowerShell script (default) or CMD (--cmd) via file or --inline
sysinfo	Collect comprehensive system information
list	List all saved hosts
remove	Remove a saved host by UUID
cp	Copy files to/from remote host
pull	Alias for cp --direction pull

Output Format

By default, agentwin prints a concise summary to stdout and saves the full result as a markdown file:

$ agentwin sysinfo --host a1b2c3d4
✓ WIN-NAS  a1b2c3d4
  OS    Windows Server 2025 Datacenter (26100)
  CPU   x64
  Disk  C: 120G(89G free) | D: 64G(62G free) | 1 unmounted
  Net   10.0.0.20/23

Full: /home/user/.config/agentwin/runs/a1b2c3d4/2026-07-12T22-30-15Z_sysinfo.md

Always read the full file at the path shown in stdout for complete results.

Output Flags

Flag	Behavior
(none)	Concise stdout + full file saved
--full	Print full output to stdout
--quiet / -q	Status code + UUID only
--json	Force JSON output to stdout
--output <path>	Custom save path
--no-save	Skip file save
--no-color	Disable ANSI colors

Credential Security

• Credentials are encrypted with Fernet (AES-128-CBC + HMAC)
• The encryption key is derived from machine_id + username + app_salt
• Stored in ~/.config/agentwin/hosts.json (cross-platform via platformdirs)
• No master password, no keyring — zero manual intervention
• Changing machine = re-authentication required (security by design)

Protocol Support

Protocol	Auth Methods	Ports
WinRM	NTLM (password)	5985 (HTTP), 5986 (HTTPS)
SSH	Key (ed25519) / Password	22

• Auto-detection: health subcommand reports which protocols are available
• Fallback chain: WinRM → SSH key → SSH password

File Transfer Strategy

Protocol	File Size	Method
SSH	Any	SFTP direct transfer (no size limit, speed = network bandwidth)
WinRM	≤ 1MB	Base64 chunked upload (limited by powershell -encodedcommand 8191-char limit)
WinRM	> 1MB	Error: prompts user to use SSH or SMB

WinRM is not suitable for large files due to SOAP/XML protocol overhead. Enable OpenSSH on Windows and use agentwin auth <host> --port 22 for large file transfers.

---

中文

项目简介

agentwin 是一个命令行工具，专为 AI agent（以及人类）设计，用于通过 WinRM 或 SSH 协议远程管理 Windows 设备。

安装

🎯 推荐：作为 AI agent skill 安装（npx skills add）

agentwin 的 skill（仓库里 skills/agentwin/SKILL.md）能被任何支持 Vercel Skills 生态的 agent（Claude Code、OpenCode、Cursor、Codex、Antigravity 等）通过 npx skills CLI 一键装上：

# 把 agentwin skill 装到指定 agent
npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a claude-code

# 一次性装到所有支持的 agent
npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a '*'

npx skills 是 Node.js 包，首次运行会自动下载，不用手动装。

🤖 给 AI agent 的一键安装提示

直接把下面这段发给 AI agent（Claude、Cursor 等）：

请帮我安装 agentwin skill。跑这条命令并把结果贴给我： npx skills add https://github.com/xiaoka76/agentwin -s agentwin -a '*' 装完后跑 npx skills list | grep agentwin 验证一下，让我知道已经激活了。

备选：uv tool install

# 装 uv（如果还没装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 装 agentwin
uv tool install agentwin

# 验证
agentwin --version

免安装直接跑：uvx

uvx 是 Python 的 npx——下载、运行、丢弃。适合临时跑命令或先体验一下：

# 不用全局装，直接跑任何子命令
uvx agentwin health 10.0.0.20
uvx agentwin sysinfo --host <uuid>
uvx agentwin --help

# 始终用最新版本
uvx --from agentwin agentwin --version

从源码装

git clone https://github.com/xiaoka76/agentwin.git
cd agentwin
uv tool install -e .

快速开始

# 1. 健康检查 — 扫描端口并检测可用协议
agentwin health 10.0.0.20

# 2. 认证 — 保存加密凭据
agentwin auth 10.0.0.20 --user Administrator --password "你的密码"

#    也可用 --method 显式指定认证方式（默认端口 5985→WinRM，22→SSH）
agentwin auth 10.0.0.20 --user Administrator --password "你的密码" --method winrm-password
agentwin auth 10.0.0.20 --user Administrator --password "你的密码" --port 2222 --method ssh-password
agentwin auth 10.0.0.20 --user Administrator --key ~/.ssh/id_rsa

# 3. 列出已保存的主机
agentwin list

# 4. 执行命令（默认 PowerShell）
agentwin execute --host a1b2c3d4 "Get-ChildItem C:\Users"
#    加 --cmd 改用 cmd.exe
agentwin execute --host a1b2c3d4 --cmd "ipconfig /all"

# 5. 采集系统信息
agentwin sysinfo --host a1b2c3d4

子命令清单

命令	说明
health	扫描目标主机的开放端口和协议
auth	认证并保存加密凭据
execute	执行单条命令（默认 PowerShell，--cmd 走 cmd.exe）
script	运行 PowerShell（默认）或 CMD（--cmd）脚本（文件或 --inline）
sysinfo	采集全面的系统信息
list	列出所有已保存的主机
remove	按 UUID 删除已保存的主机
cp	向/从远程主机复制文件
pull	cp --direction pull 的别名

输出格式说明

默认情况下，agentwin 在 stdout 打印简洁摘要，并将完整结果保存为 markdown 文件：

$ agentwin sysinfo --host a1b2c3d4
✓ WIN-NAS  a1b2c3d4
  OS    Windows Server 2025 Datacenter (26100)
  CPU   x64
  Disk  C: 120G(89G free) | D: 64G(62G free) | 1 unmounted
  Net   10.0.0.20/23

Full: /home/user/.config/agentwin/runs/a1b2c3d4/2026-07-12T22-30-15Z_sysinfo.md

务必读取 stdout 末尾路径指向的完整文件以获取全部信息。

凭据存储

• 凭据使用 Fernet（AES-128-CBC + HMAC）加密
• 加密密钥由 machine_id + username + app_salt 派生
• 存储在 ~/.config/agentwin/hosts.json（通过 platformdirs 跨平台）
• 无需主密码，无需 keyring — 零人工干预
• 换机器 = 重新认证（安全设计）

协议支持

协议	认证方式	端口
WinRM	NTLM（密码）	5985 (HTTP), 5986 (HTTPS)
SSH	密钥 (ed25519) / 密码	22

• 自动探测：health 子命令报告哪些协议可用
• 降级链：WinRM → SSH 密钥 → SSH 密码

文件传输策略

连接类型	文件大小	传输方式
SSH	任意	SFTP 直传（无大小限制，速度取决于网络带宽）
WinRM	≤ 1MB	Base64 分块上传（受 powershell -encodedcommand 命令行 8191 字符限制）
WinRM	> 1MB	报错提示用户使用 SSH 或 SMB

WinRM 因 SOAP/XML 协议开销不适合传输大文件。建议在 Windows 上启用 OpenSSH 服务，然后用 agentwin auth <host> --port 22 注册 SSH 连接以支持大文件传输。