# Windows Connections (WinRM)

> A third transport for saved connections, on the same model as the SSH servers: the credential is typed once, stored in the OS keychain, and never shown to an agent.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-09-26
- Web page: https://agentsroom.dev/docs/windows-connections

## What it does

A third transport for saved connections, on the same model as the SSH servers: the credential is typed once, stored in the OS keychain, and never shown to an agent. A **WinRM connection** reaches a Windows host through PowerShell Remoting, with NTLM for a workgroup machine or Kerberos for a domain member, including the PowerShell endpoint of an on-prem Exchange server. Agents can only read through it unless you say otherwise, and every write you allow (a `Restart-VM`, a `Set-Mailbox`, a file sent to the host) still waits for your confirmation in the agent's panel. Since 1.178.0 a file can also travel to or from the Windows host with Windows paths (`C:\Temp\dump.zip`), without OpenSSH on the host: the transfer takes the machine's administrative share (`C$`) when it is reachable, which is much faster on large files, and falls back to the PowerShell session on its own when it is not.

## Where to find it

- In a project, the terminals panel > Commands modal > **Servers** tab > New connection > Transport **WinRM**. Same place as SSH and AWS SSM.
- The first WinRM form shows a band **Windows connectors not installed** with an **Install** button: "WinRM connections use two Python packages (pypsrp, smbprotocol), installed once in a private environment". They land in a folder AgentsRoom owns (`~/.agentsroom/connectors-venv`); nothing else on the machine changes. A machine that installed the connectors before the SMB client existed keeps working and the band warns that "The SMB client (smbprotocol) is missing: file transfers go through the PowerShell runspace, which is much slower for large files." Clicking **Install** again adds it.

## How to use it

1. Servers > New connection > Transport WinRM. Enter the host name, the port (5985, or 5986 with HTTPS), the user and the password.
2. Pick the Windows authentication: **NTLM** for a workgroup machine or a local account, **Kerberos** for a domain machine. Exchange only accepts Kerberos on its endpoint; choose Endpoint **Exchange** and the form switches to Kerberos and ports 80/443 by itself.
3. From a workstation that is not joined to the domain, fill the Kerberos block: the **realm** (`CORP.LOCAL`), the **domain controller (KDC)** and the **server IP** when your DNS does not resolve the server name. AgentsRoom handles the lookups itself; your hosts file is never touched. With Kerberos you may leave the password blank to reuse the ticket of your session (`kinit`).
4. Leave **Read-only for agents** ticked unless you want agents to change things through this connection. Test the connection (a real login), then Save.
5. Click the connection: a terminal tab opens on an interactive PowerShell prompt. Or ask an agent: "list the VMs running on the hypervisor", "show the Exchange send connectors".

Same host, another endpoint or account: the **Duplicate** icon of a saved connection opens the **Duplicate connection** form pre-filled, named "<name> (copy)". Since 1.184.0 the password field reads "Leave blank to reuse the original connection's password": left blank, the copy takes the credential of the original from the keychain; a password you type wins.

## Settings

None. The connectors venv lives in the AgentsRoom data folder; deleting it uninstalls them.

## Agent tools (MCP)

- `ssh_list`: a WinRM host is listed with `kind: "winrm"`, its authentication and `readOnly`.
- `ssh_exec`: runs a PowerShell line on it (cmdlet pipelines only on an Exchange endpoint). Reads run; a write is refused on a read-only connection and confirmed by you on a writable one.
- `ssh_transfer`: moves one file in or out, nothing to install on the host (or, in download, a whole folder: see below). It tries the administrative share first and drops back to the PowerShell session when that fails, whatever the reason (port 445 filtered, share removed by group policy, access denied); the answer names the transport used and why the share was skipped, so the agent can explain a slow transfer. The remote path is an absolute Windows path (`C:\Temp\dump.zip`, `C:/Temp/dump.zip` or a `\\server\share\file` UNC path; spaces allowed, globs and relative paths refused). A download runs even on a read-only connection and lands in the project's `.agentsroom/ssh-transfers/` folder unless a local path is given; an upload is a write, refused on a read-only connection and confirmed by you on a writable one. The agent gets back a local path and a size, never the content.
- `ssh_connect`: opens the interactive PowerShell tab.
- `ssh_connection_new` with `kind: "winrm"`: proposes a host by pre-filling the form; you review and save.

## Providers

All providers, no difference: the tools live in the AgentsRoom MCP server.

## Mobile

A WinRM connection appears in the phone's SSH list with a "WinRM" tag and opens a PowerShell prompt streamed from the desktop.

## Limits

- The connector needs a Python 3 on the machine (macOS Command Line Tools, python.org, Homebrew or the distribution package). Without one the form says so.
- Kerberos on macOS and Linux needs the `gssapi` extra, compiled against the system Kerberos (`libkrb5-dev` on Debian/Ubuntu). When it is missing the band says so and NTLM keeps working. On Windows, Kerberos goes through the system (SSPI): the workstation must resolve the domain and the KDC field is ignored.
- Which PowerShell line counts as a write is decided by an allow-list of read verbs and commands (Get-*, Test-*, Measure-*, Select-*, Where-*, Format-*, `whoami`, `ipconfig`, `nslookup`...). Anything else, including method calls and redirections, asks for a confirmation on a writable connection. Language keywords (`if`, `else`, `foreach`, `try`...) are not commands, and a hyphenated word passed as an argument (a server name such as `SRV-GE`) is not taken for a cmdlet unless it starts with an approved PowerShell verb; an unknown verb in command position is still a write.
- A WinRM host cannot be a bastion, a database tunnel or a host for remote agents.
- File transfer: one file per call and no glob. One exception since 2026-09-23: a download whose remote path is a folder brings the whole folder, sub-folders included, and recreates it under the local path, but only when the administrative share carries it; over the PowerShell fallback a folder is refused and the agent archives it first with `Compress-Archive` through `ssh_exec`. The folder can be written with or without a trailing `\` (`C:\inetpub\logs\` is the same as `C:\inetpub\logs`); only the root of a drive or share is refused. Uploading a folder is not possible. The 256 MB download cap only applies to the PowerShell fallback, which holds the whole file in memory; when the administrative share serves the transfer there is no such ceiling. Above the cap the agent is told to compress on the host, and the message says why the share could not be used. The Exchange endpoint cannot carry a file at all: save a WinRM connection to the same host on its /wsman endpoint (port 5985 or 5986) and transfer through it.

## Common questions

- **I already reach my Windows server over SSH, do I need WinRM?** No. An SSH connection with the remote shell set to PowerShell is the simplest path. WinRM is for hosts without OpenSSH and for the Exchange management endpoint, which only speaks Kerberos over WinRM.
- **An agent says a command was "refused: read-only".** The connection is read-only for agents, which is the default. Open it in the Servers tab and untick "Read-only for agents" if you want writes; each one will then be confirmed by you.
- **The confirmation card never shows up.** It appears in the panel of the agent that asked ("Allow this write?", with **Run it** / **Decline**), and that agent is marked "needs input". It expires after two minutes with nothing run: the agent is told nobody answered, not that you refused.
- **Can agents browse my SMB network shares through it?** No. There is no shares browser and no share tool: the only use of SMB is the file (or, in download, the folder) a transfer carries over the machine's administrative share. Reach any other share from the PowerShell prompt or with an SSH connection to the same host.
- **A large file takes forever to transfer.** That is the PowerShell fallback, which encodes the file through the session. The answer the agent gets names the transport and why the administrative share was skipped: most often port 445 is blocked between your machine and the host, or the SMB client is not installed yet (the band in the WinRM form says so, click **Install**).
- **Every line of a read-only network analysis asked for my confirmation.** Fixed on 2026-09-22: a server name with a dash (`-ComputerName SRV-GE`) or an `if` / `foreach` in the line was read as an unknown command, so as a write. Those lines now run as reads. Since 2026-09-26 the same goes for a line with a hashtable argument (`Get-WinEvent -FilterHashtable @{LogName='System'; Id=20}`): its entries are values, not commands.
- **Does the password ever reach the agent?** No. The desktop hands it to the connector on its standard input; it is never on a command line, in the environment or in a file.
- **The agent says my `C:\...` path is refused.** Since 1.178.0 drive-letter and UNC paths are accepted on a WinRM connection. Check that the path is absolute, names one file and has no `* ? " < > |`; a path ending with a separator is a folder and is refused.
- **I duplicated a Kerberos connection and the copy cannot sign in.** Fixed in 1.184.0: before, a duplicate was saved without its password, and with Kerberos a blank password means "use my session ticket", so the copy failed from a Mac outside the domain while the original worked. Update, then duplicate again and leave the password blank (it is reused) or type it.
- **Can an agent fetch a log or a dump from the Windows server?** Yes, with `ssh_transfer` ("download the IIS log to the project"): it works on a read-only connection and the file lands under `.agentsroom/ssh-transfers/`. Sending a file to the host is a write and asks for your confirmation.
- **Can an agent download a whole log folder from a read-only server?** Yes, since 2026-09-23, when port 445 answers: ask it to download the folder (for example `C:\inetpub\logs\LogFiles`) and it arrives whole, with no size cap and no archive to create on the host. If the share is blocked, the agent is told why and has to archive the folder first, which a read-only connection may not allow.

## Related

- [SSH Connections](https://agentsroom.dev/docs/ssh-connections.md): the Servers tab this transport lives in, and the SSH + PowerShell shell option.
- [Secret Manager](https://agentsroom.dev/docs/secret-manager.md): where the credentials live.
- [AgentsRoom MCP](https://agentsroom.dev/docs/agentsroom-mcp.md): the server that exposes the tools.
- [Windows and Linux](https://agentsroom.dev/docs/windows-and-linux.md): platform notes.