Windows Connections (WinRM)
- Desktop, mobile and web
- All plans
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. CredSSP covers the second hop: a session on one server that must in turn reach another one (a file server querying Active Directory). Agents can only read through it unless you say otherwise, and the writes you allow (a Restart-VM, a Set-Mailbox, a file sent to the host) wait for your confirmation in the agent's panel: every one of them by default, only the risky ones, or none, as you choose per connection. 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
- Servers > New connection > Transport WinRM. Enter the host name, the port (5985, or 5986 with HTTPS), the user and the password.
- 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.
- 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). - Need the second hop (the remote session must reach another server with your account)? Pick CredSSP. HTTPS is then forced and the server certificate is checked; the password is required, and a warning reminds you that CredSSP hands that password to the server. The Kerberos block stays available and optional: with a realm the account is proven with Kerberos inside CredSSP, without one with NTLM.
- Leave Read-only for agents ticked unless you want agents to change things through this connection. Test the connection (a real login), then Save.
- 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
Per connection, in the WinRM connection form (Servers tab, edit the connection):
- Windows authentication (
msAuth, synced with your account): NTLM (default), Kerberos, or CredSSP (not on the Exchange endpoint). With CredSSP the HTTPS box is ticked and locked, and the password field is required. - Read-only for agents (default: ticked). Agents can only read; every write is refused.
- Confirm agent writes (shown once "Read-only for agents" is unticked; stored as
writeConfirmon the connection, synced with your account; default Every write):- Every write: each command that may change something waits for your OK in the agent's panel.
- Risky ones only: low risk writes run straight away (an
Export-*cmdlet,Out-Fileor a>redirection,New-Item/mkdir,Copy-Item,Compress-Archive, session state such asSet-LocationorStart-Sleep, a .NET call that cannot change state such as.Connect()or.AddDays(),wpr, a file upload). Anything that stops, removes, changes a setting, starts a process, runs a script or callsInvoke-*still waits for your OK, and so does any command the classifier does not know. - Never: agents run every command without asking, writes included. Your responsibility.
Only you set this level: an agent that saves or edits the connection through ssh_connection_save cannot change it. The connectors venv lives in the AgentsRoom data folder; deleting it uninstalls them.
Agent tools (MCP)
ssh_list: a WinRM host is listed withkind: "winrm", its authentication andreadOnly.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, on a writable one, confirmed by you as much as the connection's Confirm agent writes level says.ssh_listshows that level to the agent (writeConfirm).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.zipor a\\server\share\fileUNC 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 (it counts as a low risk write: the Risky ones only level lets it through). The agent gets back a local path and a size, never the content.ssh_connect: opens the interactive PowerShell tab.ssh_connection_newwithkind: "winrm": proposes a host by pre-filling the form; you review and save.ssh_connection_new/ssh_connection_saveacceptmsAuth: "credssp". HTTPS is set automatically, and the password is always typed by you (or taken from a vault secret you name), never by the agent.
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
gssapiextra, compiled against the system Kerberos (libkrb5-devon 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,nslookup...). For Windows tools that both read and write, the sub-command decides:repadmin /showrepl,netdom query,net group ... /domain,wmic ... get,setspn -L,ipconfig /allare reads, whilerepadmin /syncall,net user bob /add,ipconfig /release,w32tm /resyncare writes. 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 asSRV-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. - CredSSP: HTTPS only, and the certificate must be issued for the host name of the connection by an authority your computer trusts (Keychain on macOS, the certificate store on Windows). This needs Python 3.10 or newer for the connectors; with an older Python only public authorities are recognized and the band says so. AgentsRoom never turns CredSSP on for the server and never falls back to NTLM or Kerberos. A file transfer on a CredSSP connection does not take the administrative share (SMB cannot use CredSSP), so it goes through the PowerShell session.
- The Exchange endpoint runs one pipeline of cmdlets per line and exposes only the Exchange cmdlets your Exchange role allows, plus a few generic ones.
Where-Object,ForEach-ObjectandSort-Objectanswer "is not recognized": filter with the cmdlet's own-Identityor-Filter "..."and pick properties withSelect-Object.Format-List,Format-TableandOut-Stringat the end of a line are applied by AgentsRoom to what comes back; without them each object lists all its properties. - 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-Archivethroughssh_exec. The folder can be written with or without a trailing\(C:\inetpub\logs\is the same asC:\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; they are then confirmed by you as Confirm agent writes says.
- Is there a YOLO mode? I don't want to confirm every write during a troubleshooting session. Yes, per connection: untick "Read-only for agents", then set Confirm agent writes to Risky ones only (exports, new files and folders, copies run without asking; stop / remove / configure still ask) or Never (nothing is confirmed, at your own risk).
- 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 anif/foreachin 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. repadmin /showrepl(ornetdom query,wmic ... get) asks for my confirmation. Fixed in the version released after 2026-11-02: these Active Directory and Windows diagnostic tools were unknown to the read list, so every call counted as a write. Their reading sub-commands now run as reads; the ones that change something (repadmin /syncall,net user ... /add,ipconfig /release) still ask.- My command works on the server but fails when it reaches Active Directory or another share ("access denied"). That is the second hop: NTLM and Kerberos do not let the remote session reuse your account. Switch the connection to CredSSP. Test connection then says whether the second hop works ("The second hop works") or not.
- The test says "CredSSP is disabled on this server". An administrator must enable it on the server (
Enable-WSManCredSSP -Role Server, or the WinRM group policy). AgentsRoom changes nothing on the server. - The test says the server certificate was refused. With CredSSP the HTTPS certificate is checked: use the exact host name the certificate was issued for (its FQDN, with the server IP field if your DNS does not resolve it), and make sure the authority that issued it is trusted by your computer (Keychain Access on macOS).
- Is CredSSP safe? It hands your password to the remote server, which can reuse it to sign in elsewhere as you. Use it only on servers you trust and only when you need the second hop; the form says so next to the choice.
- My Exchange connection fails with "Bad HTTP response... Code: 415" right after signing in. Fixed in the version released after 2026-11-05: on an Exchange server offering several sign-in schemes (
Kerberos, Negotiate, NTLM, typical of Exchange 2010), AgentsRoom signed in with one under which Exchange refuses the encrypted messages that follow. It now uses Kerberos, like the Windows client. If a 415 still appears, the message says what the server offered; an Exchange administrator can check the Kerbauth native module of the PowerShell virtual directory in IIS. - On Exchange,
Where-Object(orSort-Object,ForEach-Object) "is not recognized". That endpoint only exposes the Exchange cmdlets your role allows and a few generic ones, and refuses script blocks. Filter with the cmdlet itself (Get-Mailbox -Identity x,Get-Mailbox -Filter "Name -like 'a*'"). - 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: the Servers tab this transport lives in, and the SSH + PowerShell shell option.
- Secret Manager: where the credentials live.
- AgentsRoom MCP: the server that exposes the tools.
- Windows and Linux: platform notes.