PowerShell Remoting Profiles with Windows Terminal

I have jumped in the deep end and fully committed to Windows Terminal as my default PowerShell environment. I love having one interface with tabs for different terminal profiles. Windows Terminal makes it easy for me to have tabs open to PowerShell 7, Windows PowerShell, an Ubuntu instance or even a PowerShell session with no profile. The last piece I needed was an easy way to launch a Windows Terminal profile and connect to a remote computer. Want to see how I did it?

First I created a new profile in my Windows Terminal settings. I'm going to assume you know how to do that or can figure it out. If you copy and paste an existing profile, don't forget to set a new GUID.  For my first remote profile, I wanted to create a PowerShell remoting session to my test domain controller DOM1. Here's my Windows Terminal profile for that part.

{
        "acrylicOpacity": 0.5,
        "background": "#0a52e2",
        "closeOnExit": true,
        "colorScheme": "Jeff",
        "commandline": "powershell.exe -nologo -noprofile -noexit -file c:\\scripts\\wtpsremote.ps1 dom1",
        "cursorColor": "#FFFFFF",
        "cursorShape": "underscore",
        "fontFace": "Cascadia Code",
        "fontSize": 14,
        "guid": "{b89c512a-cd2b-4fb4-a6d2-3366cee85970}",
        "historySize": 9001,
        "icon": "ms-appx:///ProfileIcons/{61c54bbd-c2c6-5271-96e7-009a87ff44bf}.png",
        "name": "DOM1",
        "padding": "0, 0, 0, 0",
        "snapOnInput": true,
        "startingDirectory": "%USERPROFILE%",
        "tabTitle": "PSRemote: DOM1.Company.Pri",
        "useAcrylic": false
   },

The magic bits are centered on the commandline setting. In my profile I'm telling Windows Terminal to start Windows PowerShell with no logo, no profile and not to exit. I'm then providing a file and an argument for that script. I initially fussed with -Command but eventually found it easier to simply call a script file. The wtpsremote.ps1 file, creates the remoting session.

#requires -version 5.1

#wtpsremote.ps1

[cmdletbinding()]
Param(
    [Parameter(Position = 0, Mandatory, HelpMessage = "Specify remote computer name")]
    [ValidateNotNullOrEmpty()]
    [string]$Computername,
    [pscredential]$Credential,
    [Parameter( HelpMessage = "A profile script to run in the remote session")]
    [ValidateScript( {Test-Path $_})]
    [string]$RemoteProfile = "C:\scripts\RemoteProfile.ps1",
    [Parameter(HelpMessage = "Specify a remote endpoint other than the default Microsoft.powershell")]
    [string]$ConfigurationName,
    [int32]$Port,
    [switch]$UseSSL
)

#remove this this parameter if specified since it can't be used to create a new PSSession
[void]($PSBoundParameters.Remove("RemoteProfile"))

#Create a new remoting session splatting the parameters passed to this script
$remote = New-PSSession @PSBoundParameters

#run the remote profile script
if ($RemoteProfile) {
    Invoke-Command -Session $remote -FilePath $RemoteProfile -HideComputerName |
        Select-Object -property * -ExcludeProperty runspaceID |
        Format-Table -AutoSize
}

#open the pssession
Enter-PSSession -session $remote

$msg = @"
 Reminder:                                                                        
 Remove the `$remote pssession after you exit and before you close the profile tab.
                                                                                  
 PS C:\> `$remote | Remove-PSSession                                               
 PS C:\> exit                                                                     
"@

#you may need to adjust colors based on your profile settings
Write-host $msg -ForegroundColor Magenta -BackgroundColor Gray

The script takes a number of parameters related to creating a new PSSession, which it does and then connects to it. And the script goes a bit further.

Normally, when you launch a PowerShell remoting session, no profile scripts are run. But this script lets you specify local file that can be run remotely, in essence as a profile script. This is the default I use.

#requires -version 5.1

#this is a remote profile script

#create a new prompt function for the remote session
#how long has this session been running?
$initiated = Get-Date

$remotePrompt = {
    #display the session runtime without the milliseconds
    $ts = ((Get-Date) - $initiated).ToString().split(".")[0]
    Write-Host ">$ts< " -ForegroundColor yellow -nonewline
    "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) ";
}

Set-Item -Path function:\prompt -Value $remotePrompt -Force

Set-Location C:\
Clear-Host

#display some information about the remote computer
Get-CimInstance -ClassName Win32_OperatingSystem |
Select-Object @{Name="Computer";Expression={$_.CSName}},
@{Name="OS";Expression = {$_.Caption}},
@{Name="PSVersion";Expression = {$PSVersionTable.PSVersion}},
@{Name="User";Expression = {Whoami.exe}}

The profile script defines a prompt for the remote session that will show you how long you have been connected. It also displays a summary about the remote computer. You can add whatever else you might need such as defining variables, aliases or importing modules.

Going back to wtpsremote.ps`, the last step is to display a reminder.  If you simply close the profile tab, the remoting session will remain in a disconnected state until the remote computer cleans it up or is rebooted. To be a good network citizen, when you are finished type 'exit' to leave the remote session. This will dump you back in the terminal profile running Windows PowerShell. You should remove the pssession and then you can exit or close the profile tab.

Here's what I get when I open this Windows Terminal profile.

As I use the terminal, the prompt updates to show me how long I have been connected. When finished, I can exit.

It is at this point that I would remove the pssession and exit the tab.

My connection script also lets you specify alternate credentials and even an alternate endpoint. Here's a profile for SRV1 that connects with specific credentials and connects to the PowerShell 7 endpoint.

{
    "acrylicOpacity": 0.5,
    "background": "#808285",
    "closeOnExit": true,
    "colorScheme": "Jeff",
    "commandline": "powershell.exe -nologo -noprofile -noexit -file c:\\scripts\\wtpsremote.ps1 -computername srv1 -credential company\\administrator -configurationname PowerShell.7.0.0-rc.2",
    "cursorColor": "#FFFFFF",
    "cursorShape": "underscore",
    "fontFace": "Cascadia Code",
    "fontSize": 14,
    "guid": "{173fd06c-883a-404b-97bd-9f955a0e85f0}",
    "historySize": 9001,
    "icon": "ms-appx:///ProfileIcons/{61c54bbd-c2c6-5271-96e7-009a87ff44bf}.png",
    "name": "SRV1",
    "padding": "0, 0, 0, 0",
    "snapOnInput": true,
    "startingDirectory": "%USERPROFILE%",
    "tabTitle": "PSRemote: SRV1.Company.Pri",
    "useAcrylic": false
},

I am finding these remote tabs very useful and hope you will too. Enjoy!

Update

I updated my techniques and code for creating remote profiles in Windows Terminal to now support cross-platform. Read about it here.

---

---