Start Windows Sandbox with parameters

I use Windows Sandbox a lot for testing Endpoint Manager packages or software. Sometimes you want to start it with specific options (Connect a folder on your hard drive or start without a network connection). You must create a custom configuration file (.wsb) with those options. This blog post shows you how to start Windows Sandbox using PowerShell with parameters without creating multiple configuration files.

What is Windows Sandbox?

“Windows Sandbox provides a lightweight desktop environment to run applications in isolation safely. Software installed inside the Windows Sandbox environment remains “sandboxed” and runs separately from the host machine. A sandbox is temporary. When it’s closed, all the software and files and the state are deleted.”

How do you install Windows Sandbox?

You can install it by adding it as a Windows Feature using Add/Remove programs or by running:

Enable-WindowsOptionalFeature -Online -FeatureName:Containers-DisposableClientVM -NoRestart:$True

How the script works

I used all the options specified on https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-sandbox/windows-sandbox-configure-using-wsb-file to create a Start-Sandbox function which creates a .wsb file (Basically an XML actually) It creates a very basic one if you don’t specify any parameter. Still, it adds more lines to the .wsb file if you specify more parameters. After the creation of the .wsb file, the script starts Windows Sandbox using it and then deletes the configuration file from your temp directory.

The parameters that you can use

Below are all the parameters that you can use in the Start-Sandbox Function:

vGPUdisable

Use this to disable vGPU sharing, making the Windows Sandbox use software rendering.

AudioInputDisable

Use this to disable the microphone access in Windows Sandbox.

ClipboardRedirectionDisable

Use this to completely disable the copy/paste function between your computer and Windows Sandbox (In and outgoing).

LogonCommand

Specify the path to the executable or script that should be started when the Windows Sandbox is running.

MappedFolder

Use this to specify a local folder you want to see in your Windows Sandbox session, for example, c:\temp.

MappedFolderWriteAccess

Use this to switch from Read-Only mode to Read-Write mode for the MappedFolder you specified.

MemoryInMB

Use this to specify the amount of RAM in MBS that Windows Sandbox should use. Specifying something below 2Gb will show a warning telling you that Windows Sandbox could allocate more memory if needed.

NetworkingDisable

Use this to disable networking in Windows Sandbox, it could be a good thing when testing software that you’re not entirely sure about 😉

PrinterRedirectionEnable

Use this to connect your local printers in Windows Sandbox.

ProtectedClientEnable

Use this so that Windows Sandbox will run with extra security mitigations enabled.

VideoInputEnable

Use this to enable video input in Windows Sandbox.

Using the Start-Sandbox function

In the example below, I use the following command line to start an 8Gb RAM Windows Sandbox, printers connected, d:\temp directory connected in Read-Write mode, and an automatically started Windows ISE session.

Start-Sandbox -MappedFolder d:\temp -MappedFolderWriteAccess -PrinterRedirectionEnable -MemoryInMB 8192 -LogonCommand C:\Windows\system32\WindowsPowerShell\v1.0\powershell_ise.exe

The script

Below is the script for the Start-Sandbox function:

#https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-sandbox/windows-sandbox-configure-using-wsb-file
function Start-Sandbox {
    param(
        [parameter(Mandatory = $false)][string]$MappedFolder,
        [parameter(Mandatory = $false)][string]$MemoryInMB,
        [parameter(Mandatory = $false)][string]$LogonCommand,
        [switch]$vGPUdisable,
        [switch]$AudioInputDisable,
        [switch]$ClipboardRedirectionDisable,
        [switch]$MappedFolderWriteAccess,
        [switch]$NetworkingDisable,
        [switch]$PrinterRedirectionEnable,
        [switch]$ProtectedClientEnable,
        [switch]$VideoInputEnable
    )

    #Validate if $mappedfolder exists
    if ($MappedFolder) {
        if (Test-Path $MappedFolder -ErrorAction SilentlyContinue) {
            Write-Host ("Specified {0} path exists, continuing..." -f $MappedFolder) -ForegroundColor Green
        }
        else {
            Write-Host ("Specified {0} path doesn't exist, exiting..." -f $MappedFolder) -ForegroundColor Red
            return
        }
    }
    #Set Read-Only or Read-Write
    if ($MappedFolderWriteAccess) {
        $WriteAccess = 'false'
    }
    else {
        $WriteAccess = 'true'
    }
    #Create .wsb config file
    $wsb = @()
    $wsblocation = "$($env:Temp)\sandbox.wsb"
    $wsb += "<Configuration>"
    if ($vGPUdisable) {
        $wsb += "<VGpu>Disable</VGpu>"
    }

    if ($AudioInputDisable) {
        $wsb += "<AudioInput>Disable</AudioInput>"
    }

    if ($ClipboardRedirectionDisable) {
        $wsb += "<ClipboardRedirection>Disable</ClipboardRedirection>"
    }

    if ($MappedFolder) {
        $wsb += "<MappedFolders>"
        $wsb += "<MappedFolder>"
        $wsb += "<HostFolder>$($MappedFolder)</HostFolder>"
        $wsb += "<ReadOnly>$($WriteAccess)</ReadOnly>"
        $wsb += "</MappedFolder>"
        $wsb += "</MappedFolders>"
    }

    if ($null -ne $MemoryInMB) {
        $wsb += "<MemoryInMB>$($MemoryInMB)</MemoryInMB>"
        if ($MemoryInMB -le 2048) {
            Write-Host "$($MemoryInMB) Mb(s) specified, Windows Sandbox will automatically allocate more if needed..." -ForegroundColor Yellow
        }
    }

    if ($NetworkingDisable) {
        $wsb += "<Networking>Disable</Networking>"
    }

    if ($LogonCommand) {
        $wsb += "<LogonCommand>"
        $wsb += "<Command>$($LogonCommand)</Command>"
        $wsb += "</LogonCommand>"
    }

    if ($PrinterRedirectionEnable) {
        $wsb += "<PrinterRedirection>Enable</PrinterRedirection>"
    }

    if ($ProtectedClientEnable) {
        $wsb += "<ProtectedClient>Enable</ProtectedClient>"
    }

    if ($VideoInputEnable) {
        $wsb += "<VideoInput>Enable</VideoInput>"
    }

    $wsb += "</Configuration>"
    
    #Create sandbox .wsb file in $env:\temp and start Windows Sandbox using it
    $wsb | Out-File $wsblocation -Force:$true
    Write-Host ("Starting Sandbox...") -ForegroundColor Green
    Invoke-Item $wsblocation
    #Wait for Windows Sandbox to start and delete the sandbox config file
    Start-Sleep -Seconds 5
    Remove-Item -Force:$true -Confirm:$false -Path $wsblocation
    Write-Host ("Done!") -ForegroundColor Green
}

Adding the Start-Sandbox function to the PowerShell profile

You can add the Start-Sandbox function to your profile by editing it (notepad $profile) and adding the following:

. c:\data\Start-Sandbox.ps1

Download the script(s) from GitHub here

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.