Windows Connections (WinRM)

  • Desktop, mobile and web
  • All plans
View as Markdown

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