Windows Sandbox - Config Files
Published Feb 21 2019 12:37 PM 174K Views
Microsoft

Since the initial announcement of Windows Sandbox, we have received overwhelmingly positive feedback. Thank you for your support! We are glad that this feature resonates with the Windows community. 

 

One of the most requested features from our customers is the ability to automatically launch an app or script in the sandbox. Coincidentally, this also aligned with our feature roadmap and is now available in Windows Insider builds. 

 

Windows Sandbox now has support for simple configuration files (.wsb file extension), which provide minimal scripting support. You can use this feature in the latest Windows Insider build 18342.  

 

As always, we rely on your feedback to build features allowing our users to achieve more. 

 

NOTE: Please note that this functionality is still in development and subject to change.  

 

Overview

Sandbox configuration files are formatted as XML, and are associated with Windows Sandbox via the .wsb file extension. A configuration file allows the user to control the following aspects of Windows Sandbox:

 

  1. vGPU (virtualized GPU)
    • Enable or Disable the virtualized GPU. If vGPU is disabled, Sandbox will use WARP (software rasterizer).
  2. Networking
    • Enable or Disable network access to the Sandbox.
  3. Shared folders
    • Share folders from the host with read or write permissions. Note that exposing host directories may allow malicious software to affect your system or steal data.
  4. Startup script
    • Logon action for the sandbox.

 

SandboxConfigFile.png

 

As demonstrated in the examples below, configuration files can be used to granularly control Windows Sandbox for enhanced isolation.

 

Double click a config file to open it in Windows Sandbox, or invoke it via the command line as shown:

 

C:\Temp> MyConfigFile.wsb

 

Keywords, values and limits

 

VGpu

Enables or disables GPU sharing.

 

<VGpu>value</VGpu> 

 

Supported values:

  • Disable – disables vGPU support in the sandbox. If this value is set Windows Sandbox will use software rendering, which can be slower than virtualized GPU.
  • Default – this is the default value for vGPU support; currently this means vGPU is enabled.

Note: Enabling virtualized GPU can potentially increase the attack surface of the sandbox.

 

Networking

Enables or disables networking in the sandbox. Disabling network access can be used to decrease the attack surface exposed by the Sandbox.

 

<Networking>value</Networking>

 

Supported values:

  • Disable – disables networking in the sandbox.
  • Default – this is the default value for networking support. This enables networking by creating a virtual switch on the host, and connects the sandbox to it via a virtual NIC.

 Note: Enabling networking can expose untrusted applications to your internal network.

 

MappedFolders

Wraps a list of MappedFolder objects.

 

<MappedFolders>
list of MappedFolder objects
</MappedFolders>

 

Note: Files and folders mapped in from the host can be compromised by apps in the Sandbox or potentially affect the host. 

 

MappedFolder 

Specifies a single folder on the host machine which will be shared on the container desktop. Apps in the Sandbox are run under the user account “WDAGUtilityAccount”. Hence, all folders are mapped under the following path: C:\Users\WDAGUtilityAccount\Desktop.

 

E.g. “C:\Test” will be mapped as “C:\users\WDAGUtilityAccount\Desktop\Test”.

 

<MappedFolder>
    <HostFolder>path to the host folder</HostFolder>
    <ReadOnly>value</ReadOnly>
</MappedFolder>

 

HostFolder: Specifies the folder on the host machine to share to the sandbox. Note that the folder must already exist the host or the container will fail to start if the folder is not found.

 

ReadOnly: If true, enforces read-only access to the shared folder from within the container. Supported values: true/false.

 

Note: Files and folders mapped in from the host can be compromised by apps in the Sandbox or potentially affect the host.

 

LogonCommand

Specifies a single Command which will be invoked automatically after the container logs on.

 

<LogonCommand>
   <Command>command to be invoked</Command>
</LogonCommand>

 

Command: A path to an executable or script inside of the container that will be executed after login.

 

Note: Although very simple commands will work (launching an executable or script), more complicated scenarios involving multiple steps should be placed into a script file. This script file may be mapped into the container via a shared folder, and then executed via the LogonCommand directive.

 

Example 1:

The following config file can be used to easily test downloaded files inside of the sandbox. To achieve this, the script disables networking and vGPU, and restricts the shared downloads folder to read-only access in the container. For convenience, the logon command opens the downloads folder inside of the container when it is started.

 

Downloads.wsb

<Configuration>
<VGpu>Disable</VGpu>
<Networking>Disable</Networking>
<MappedFolders>
   <MappedFolder>
     <HostFolder>C:\Users\Public\Downloads</HostFolder>
     <ReadOnly>true</ReadOnly>
   </MappedFolder>
</MappedFolders>
<LogonCommand>
   <Command>explorer.exe C:\users\WDAGUtilityAccount\Desktop\Downloads</Command>
</LogonCommand>
</Configuration>

 

Example 2

The following config file installs Visual Studio Code in the container, which requires a slightly more complicated LogonCommand setup.

 

Two folders are mapped into the container; the first (SandboxScripts) contains VSCodeInstall.cmd, which will install and run VSCode. The second folder (CodingProjects) is assumed to contain project files that the developer wants to modify using VSCode.

 

With the VSCode installer script already mapped into the container, the LogonCommand can reference it.

 

VSCodeInstall.cmd

REM Download VSCode
curl -L "https://update.code.visualstudio.com/latest/win32-x64-user/stable" --output C:\users\WDAGUtilityAccount\Desktop\vscode.exe
 
REM Install and run VSCode
C:\users\WDAGUtilityAccount\Desktop\vscode.exe /verysilent /suppressmsgboxes

 

VSCode.wsb

<Configuration>
<MappedFolders>
   <MappedFolder>
     <HostFolder>C:\SandboxScripts</HostFolder>
     <ReadOnly>true</ReadOnly>
   </MappedFolder>
   <MappedFolder>
     <HostFolder>C:\CodingProjects</HostFolder>
     <ReadOnly>false</ReadOnly>
   </MappedFolder>
</MappedFolders>
<LogonCommand>
   <Command>C:\users\wdagutilityaccount\desktop\SandboxScripts\VSCodeInstall.cmd</Command>
</LogonCommand>
</Configuration>

 

Conclusion

We look forward to your feedback.

 

Cheers,

Margarit Chenchev, Erick Smith, Paul Bozzay, Deepti Bhardwaj & Hari Pulapaka

(Windows Sandbox team) 

31 Comments
Copper Contributor
Feedback link isn't loading on my phone, so submitting it here instead. 1. Add option in .wsb to prevent writing to clipboard from sandbox. Right now, you can copy files from sandbox to host. 2. Allow multiple instances of sandbox to be created. 3. Add resource options to .wsb config file (e.g. vCPUs, Memory). 4. Allow users to launch Sandbox without UAC prompt.
Copper Contributor

I really do apreciate your work! Great job so far!

My wish for future release: possibility to specify Apps already installed on the host, that could be also be "preinstalled" in sandbox (like the edge browser)

 

i know, i could use a v-box, but then we are right in the dabate slim, empty, but out of the box sandbox vs. fully customizable, heavy recource depending/eating vm but with all apps preinstalled

Copper Contributor

In Windows 10 build 18850.1000, Windows Sandbox ignores the <Networking>Disable</Networking> command. Other commands for mapped folders and logon commands work fine. Has anybody else encountered this issue?

Copper Contributor
I registered just to reply to echo the above comment: I see no evidence that a script is running. All commands in the script seem to be ignored. Sandbox opens the same way regardless of script or not. Anyone else with this problem?
Copper Contributor

@scratchb1 and @_Mathias_, make sure your config files have the proper XML syntax.  Need to have the <configuration> at top and the </configuration> at bottom.

 

Example:

<Configuration>
<LogonCommand>
<Command>command to be invoked</Command>
</LogonCommand>
</Configuration>

 

Copper Contributor
Sandbox opens the demonstration script but does not do anything once opened. I'm on Pro build 18362.53 version 1903. Any other thoughts?
Copper Contributor

@scratchb1 Can you paste the exact lines of your wsb file you’re trying?  I can try on my own sandbox and see what’s up. 

Copper Contributor
I'm trying, but I get this warning: Your post has been changed because invalid HTML was found in the message body. The invalid HTML has been removed. Please review the message and submit the message when you are satisfied.
Copper Contributor

Even when set the comment field to rich text?  The code from this page copies and pastes ok.  Maybe try a screenshot of your code and insert image. 

7BAAF6A5-89E8-4F00-AA42-4A5F3F17D417.jpeg

 

Brass Contributor

I had Sandbox working perfectly, then I ran a recent Windows Update and now PowerShell & other things are broken in Windows Sandbox, complaining "Windows Sandbox is erroring saying Version v4.0.30319 of the .NET Framework is not installed and it is required to run version 3 of Windows PowerShell"

 

It's broken now Smiley Sad

Copper Contributor
This was the feature that I was most looking forward to in 1903. Here are my initial thoughts: The only valid configuration values are Disable and Default? What about Enable? Why should my stored configuration files change functionality at the whim of the next release of Sandbox? (if you decide that the "default" should be disabled instead of enabled?). I too am getting an error that PowerShell won't run. On one machine I'm also getting Error 0x80070015: The device is not ready and Sandbox won't start. How do I get a bigger C: drive? 40Gb is pretty small these days when I have 200Gb on my phone. Seems like this should be a configuration parameter. One of the first things I need to script is changing the theme of the sandbox, so that I don't make a mistake and confuse one window for another. I agree with the other who said I should be able to block the host clipboard to be read-only from the Sandbox.
Copper Contributor
After playing with creating configuration files, the MappedFolder feature is pretty disappointing. Here is a list of things that I tried that failed:
  1. Mount an ISO on the host before the Sandbox then use MappedFolder to map that ISO into the Sandbox (get confusing error when launching Sandbox).
  2. Mount the root of any drive (get confusing error when launching Sandbox).
  3. Mount a path containing an ISO then try to mount it in the Sandbox (refuses to mount the ISO).
  4. Copy the ISO file to drive C: and then mount it (refuses to mount the ISO).
  5. Do all the above with a tiny ISO (thinking that size might be the problem), nope.
  6. Mount two paths that end in folders with the same name (throws error, file already exists). Disappointing.
I think I'll go back to my test virtual machine, it's not activated either, but at least it works.
Copper Contributor

Hi,

 

Why when using  vGPU enable  I get this error 

Creation of a virtual GPU on the adapter (0xffffd08254688000) failed with the status (3221225485), reason (DXGK_VGPU_FAILURE_IOMMU_ENABLE)

 

I have AMD 1950x  and Nvidia 1080GTX using WDDM 2.6 newest drivers , 1903 build 145.     I tried to Enable IOMMU  in Bios or Disable, it always the same.

Any idea ?

 

 

 

Log Name: Microsoft-Windows-DxgKrnl-Admin
Source: Microsoft-Windows-DxgKrnl
Date: 08/06/2019 18:15:59
Event ID: 445
Task Category: (269)
Level: Error
Keywords: (1)
User: SYSTEM
Computer: DESKTOP-xdsa
Description:
Creation of a virtual GPU on the adapter (0xffffd08254688000) failed with the status (3221225485), reason (DXGK_VGPU_FAILURE_IOMMU_ENABLE)
Event Xml:
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event">
<System>
<Provider Name="Microsoft-Windows-DxgKrnl" Guid="{802ec45a-1e99-4b83-9920-87c98277ba9d}" />
<EventID>445</EventID>
<Version>1</Version>
<Level>2</Level>
<Task>269</Task>
<Opcode>0</Opcode>
<Keywords>0x800000000000001</Keywords>
<TimeCreated SystemTime="2019-06-08T15:15:59.025667600Z" />
<EventRecordID>16</EventRecordID>
<Correlation />
<Execution ProcessID="6900" ThreadID="10768" />
<Channel>Microsoft-Windows-DxgKrnl-Admin</Channel>
<Computer>DESKTOP-xdsa</Computer>
<Security UserID="S-1-5-18" />
</System>
<EventData>
<Data Name="pDxgAdapter">0xffffd08254688000</Data>
<Data Name="VirtualFunctionIndex">65535</Data>
<Data Name="bSecure">true</Data>
<Data Name="Status">3221225485</Data>
<Data Name="FailureType">6</Data>
</EventData>
</Event>

Iron Contributor

Is there official Microsoft documentation about all the information about how sandbox works, configuration etc? I don't blog post is sufficient resource. For example if you want to configure your sandbox to your requirements (like Chrome installed, chocolatey installed, powershell modules etc) it seems running startup script each time will be overkill. Looking into possibility of using layer on top of base layer (like in docker image) type of functionality.

Copper Contributor

Microsoft,  do you know why this error happens everytime I open Windows Sandbox?

 

Because vGPU doesn't work...  it says on the Event Viewer.    only shown in  Custom Views and Administrative Events.

Copper Contributor

I wish for the option to choose a destination on the VM where the folder will be mapped, instead of defaulting to on the desktop.
At the very least, please add a <shutdownCommand> so you can command the VM to run a set of a predefined set of commands that saves valuable data before destroying itself.

Anyway, great program overall, one of the best functions for windows in years!

Copper Contributor

Hi there! Is it possible to expose an USB device (an OBD II USB reader) to Windows Sandbox? I tried with the following, but no luck...

        <MappedFolder>
            <HostFolder>\Device\USBPDO-7</HostFolder>
            <ReadOnly>false</ReadOnly>
        </MappedFolder>
Microsoft

To follow-up on DJ's question - is there a way to force USB devices to only open in the sandbox?

Copper Contributor

How about a recipe for Visual Studio proper, which is infamous for not uninstalling everything cleanly (because other programs tend to rely on some components without taking any steps to get/keep them installed ...), and which could thus benefit quite a lot from sandboxing (to the point where creating a full VM for the purpose starts to seem attractive).

Microsoft

Is there a way to set the configure the screen resolution for the sandbox instance?

Copper Contributor

I can't seem to get environment variables to work for Mapped Folders.  Is this possible in any way?  If not, please add this functionality in future updates.

 

<MappedFolder>
    <HostFolder>%onedrive%\Sandbox</HostFolder>
    <ReadOnly>true</ReadOnly>
</MappedFolder>

Windows Sandbox should be activated when host has valid license.

this is causing problems for me

 

kkkk.png

 

jjjjj.png

 

llll.png

 

 

Copper Contributor

@HotCakeX said:

Windows Sandbox should be activated when host has valid license.

this is causing problems for me

You didn't make it clear whether the host has a valid license activated?

@naesten the host does have a valid activate Windows OS. 

Copper Contributor

Can you make an option where you can easily activate and deactivate Windows using the .wsb file?

Copper Contributor

Is there a way to start a Command Prompt or Powershell script in the foreground? The following execution at logon always puts the script in the background, meaning there's no indication when it finished:

my-project.wsb:

    <LogonCommand>
        <Command>C:\Users\WDAGUtilityAccount\Desktop\my-project\init.cmd</Command>
    </LogonCommand>

init.cmd:

@ECHO OFF

powershell.exe Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
powershell.exe "C:\Users\WDAGUtilityAccount\Desktop\my-project\provision.ps1"

provision.ps1:

#Requires -Version 5

Write-Host "Preinstall script started..."

New-Item -ItemType "directory" -Path "C:\Temp\GHIDRA"
Copy-Item -Path "C:\Users\WDAGUtilityAccount\Desktop\my-project\GHIDRA\*" -Destination "C:\Temp\GHIDRA\" -Recurse
Start-Process -FilePath "C:\Temp\GHIDRA\OpenJDK11U-jdk_x64_windows_hotspot_11.0.8_10.msi" -ArgumentList "/quiet /norestart"
Expand-Archive -Path "C:\Temp\GHIDRA\ghidra_9.1.2_PUBLIC_20200212.zip" -DestinationPath "C:\"

The reason why I don't use a Batch script is zip extraction...

Thank You for your help!

EDIT:
I found a solution how to keep a window open until it finishes it's task. We utilitize the `START` command with the maximized window flag:

START /MAX powershell.exe "C:\Users\WDAGUtilityAccount\Desktop\my-project\provision.ps1" 

 

Copper Contributor

Is there a reason why Visual C++ 2008 redist can't be installed in the Sandbox? Makes impossible to install Python 2.7:

SANDBOX_ERROR.png

Copper Contributor

Amother problem is, why changes to the hosts file not respected? If it's impossible to solve this without logoff/login, then give us an option to elevate data from the host system into the guest sandbox, before bootup. The following command not have any effect running at LogonCommand, nor later entering manually:

$file = "$env:windir\System32\drivers\etc\hosts"
"127.0.0.1 app.test" | Add-Content -PassThru $file
Start-Process 'ipconfig' -ArgumentList "/flushdns" -Wait
Brass Contributor

The next logical steps could be to implement :

- A support for running containerized Windows GUI applications on Windows desktops (based on Windows Containers). The packaging process would be 1. Start Windows Sandbox, 2. install your app, 3. pack-it as a Windows Container UI App. 

- Sandbox specifics features (Dynamics image, smart memory, kernel scheduler, Graphic virtualization) to Windows Containers v.next

- Remote Desktop App Container Host, to run RemoteApp packed as Windows Container UI App and deployed on a Windows Server.  

- Remote Desktop Session Container Host : to be used either or both like a Windows "Sandbox" server (non persistent remote desktop session), or a next gen MultiPoint server

- For security integration and multi-tenancy as an OPTION not mandatory, a LSA isolated approach for Windows Containers

- Windows "infra" services support inside Windows Containers (Active Directory services, File sharing, Print sharing, DNS Server, ...)

 

Copper Contributor

The documentation has been improved since this blog was posted: https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-sandbox/windows-sandbox-...

 

There's more options, and some fixes mentioned in the comments here. 

Copper Contributor

If I attach an external Hard drive or USB drive to my PC to copy files to the Sandbox,  It will not be recognized.

 

Best regards

Version history
Last update:
‎Dec 12 2022 11:07 AM
Updated by: