mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-06-15 18:33:43 +00:00
chore: Update Windows Sandbox TOC and sample configuration files
This commit is contained in:
Vinay Pamnani (from Dev Box)
@ -1,15 +1,16 @@
|
||||
items:
|
||||
- name: What is Windows Sandbox?
|
||||
href: windows-sandbox-overview.md
|
||||
- name: Overview
|
||||
expanded: true
|
||||
items:
|
||||
- name: What is Windows Sandbox?
|
||||
href: windows-sandbox-overview.md
|
||||
- name: Compare versions
|
||||
href: windows-sandbox-versions.md
|
||||
- name: Architecture
|
||||
href: windows-sandbox-architecture.md
|
||||
- name: Install Windows Sandbox
|
||||
href: windows-sandbox-install.md
|
||||
- name: Use Windows Sandbox
|
||||
- name: Use & configure Windows Sandbox
|
||||
href: windows-sandbox-configure-using-wsb-file.md
|
||||
- name: Tutorials
|
||||
items:
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: Windows Sandbox architecture
|
||||
description: Windows Sandbox architecture
|
||||
ms.topic: conceptual
|
||||
ms.date: 03/26/2024
|
||||
ms.date: 09/09/2024
|
||||
---
|
||||
|
||||
# Windows Sandbox architecture
|
||||
@ -27,18 +27,10 @@ Traditional VMs apportion statically sized allocations of host memory. When reso
|
||||
|
||||
## Memory sharing
|
||||
|
||||
Because Windows Sandbox runs the same operating system image as the host, it's enhanced to use the same physical memory pages as the host for operating system binaries via a technology referred to as "direct map." For example, when *ntdll.dll* is loaded into memory in the sandbox, it uses the same physical pages as those pages of the binary when loaded on the host. Memory sharing between the host and the sandbox results in a smaller memory footprint when compared to traditional VMs, without compromising valuable host secrets.
|
||||
Because Windows Sandbox runs the same operating system image as the host, it's enhanced to use the same physical memory pages as the host for operating system binaries via a technology referred to as "direct map." For example, when `ntdll.dll` is loaded into memory in the sandbox, it uses the same physical pages as those pages of the binary when loaded on the host. Memory sharing between the host and the sandbox results in a smaller memory footprint when compared to traditional VMs, without compromising valuable host secrets.
|
||||
|
||||
|
||||
|
||||
## Integrated kernel scheduler
|
||||
|
||||
With ordinary virtual machines, the Microsoft hypervisor controls the scheduling of the virtual processors running in the VMs. Windows Sandbox uses a new technology called "integrated scheduling," which allows the host scheduler to decide when the sandbox gets CPU cycles.
|
||||
|
||||
|
||||
|
||||
Windows Sandbox employs a unique policy that allows the virtual processors of the Sandbox to be scheduled like host threads. Under this scheme, high-priority tasks on the host can preempt less important work in the Sandbox. This preemption means that the most important work is prioritized, whether it's on the host or in the container.
|
||||
|
||||
## WDDM GPU virtualization
|
||||
|
||||
Hardware accelerated rendering is key to a smooth and responsive user experience, especially for graphics-intensive use cases. Microsoft works with its graphics ecosystem partners to integrate modern graphics virtualization capabilities directly into DirectX and Windows Display Driver Model (WDDM), the driver model used by Windows.
|
||||
|
||||
@ -1,11 +1,32 @@
|
||||
---
|
||||
title: Windows Sandbox configuration
|
||||
description: Windows Sandbox configuration
|
||||
title: Use and configure Windows Sandbox
|
||||
description: Use and configure Windows Sandbox
|
||||
ms.topic: how-to
|
||||
ms.date: 03/26/2024
|
||||
ms.date: 09/09/2024
|
||||
---
|
||||
|
||||
# Windows Sandbox configuration
|
||||
# Use and configure Windows Sandbox
|
||||
|
||||
To launch a Windows Sandbox with default settings, simply Locate and select Windows Sandbox on the Start menu or search for 'Windows Sandbox'. This launches a basic Sandbox with 4GB memory with the following properties:
|
||||
|
||||
- **vGPU (virtualized GPU)**: Enabled on non-ARM64 devices.
|
||||
- **Networking**: Enabled. The sandbox uses the Hyper-V default switch.
|
||||
- **Audio input**: Enabled. The sandbox shares the host's microphone input into the sandbox.
|
||||
- **Video input**: Disabled. The sandbox doesn't share the host's video input into the sandbox.
|
||||
- **Protected client**: Disabled. The sandbox doesn't have increased security settings on the Remote Desktop Protocol (RDP) session.
|
||||
- **Printer redirection**: Disabled. The sandbox doesn't share printers with the host.
|
||||
- **Clipboard redirection**: Enabled. The sandbox shares the host clipboard with the sandbox so that text and files can be pasted back and forth.
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> - Networking is enabled by default. This can expose untrusted applications to the internal network. To launch a Sandbox with networking disabled, use a custom .wsb file.
|
||||
> - With Clipboard redirection automatically enabled, you can easily copy files from the host and paste them into the Windows Sandbox window.
|
||||
|
||||
You have the freedom to open files, install applications from the web, and perform various other tasks that benefit from an isolated clean environment.
|
||||
|
||||
When you're finished experimenting, close the sandbox. A dialog box will prompt you to confirm the deletion of all sandbox content. Select "Ok" to proceed. Confirm that your host machine doesn't exhibit any of the modifications that you made in Windows Sandbox.
|
||||
|
||||
## Configure a custom Windows Sandbox
|
||||
|
||||
Windows Sandbox supports simple configuration files, which provide a minimal set of customization parameters for Sandbox. This feature can be used with Windows 10 build 18342 or Windows 11. Windows Sandbox configuration files are formatted as XML and are associated with Sandbox via the `.wsb` file extension.
|
||||
|
||||
@ -25,7 +46,7 @@ A configuration file enables the user to control the following aspects of Window
|
||||
> [!NOTE]
|
||||
> The size of the sandbox window currently isn't configurable. <!-- windows-itpro-docs #10689 -->
|
||||
|
||||
## Creating a configuration file
|
||||
## Create a configuration file
|
||||
|
||||
To create a configuration file:
|
||||
|
||||
@ -37,10 +58,8 @@ To create a configuration file:
|
||||
</Configuration>
|
||||
```
|
||||
|
||||
3. Add appropriate configuration text between the two lines. For details, see [examples](#examples).
|
||||
4. Save the file with the desired name, but make sure its filename extension is `.wsb`. In Notepad, you should enclose the filename and the extension inside double quotation marks, for example, `"My config file.wsb"`.
|
||||
|
||||
## Using a configuration file
|
||||
3. Add appropriate configuration text between the two lines. For details, see [examples](windows-sandbox-sample-configuration.md).
|
||||
4. Save the file with the desired name, but make sure its filename extension is `.wsb`. In Notepad, you should enclose the filename and the extension inside double quotation marks, for example, `"MyConfigFile.wsb"`.
|
||||
|
||||
To use a configuration file, double-click it to start Windows Sandbox according to its settings. You can also invoke it via the command line as shown here:
|
||||
|
||||
@ -48,19 +67,21 @@ To use a configuration file, double-click it to start Windows Sandbox according
|
||||
C:\Temp> MyConfigFile.wsb
|
||||
```
|
||||
|
||||
## Keywords, values, and limits
|
||||
## Configuration options
|
||||
|
||||
### vGPU
|
||||
|
||||
Enables or disables GPU sharing.
|
||||
|
||||
`<vGPU>value</vGPU>`
|
||||
```xml
|
||||
<vGPU>value</vGPU>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables vGPU support in the sandbox.
|
||||
- *Disable*: Disables vGPU support in the sandbox. If this value is set, the sandbox uses software rendering, which might be slower than virtualized GPU.
|
||||
- *Default* This value is the default value for vGPU support. Currently, this default value denotes that vGPU is enabled.
|
||||
- **Enable**: Enables vGPU support in the sandbox.
|
||||
- **Disable**: Disables vGPU support in the sandbox. If this value is set, the sandbox uses software rendering, which might be slower than virtualized GPU.
|
||||
- **Default**: This value is the default value for vGPU support. Currently, this default value denotes that vGPU is enabled.
|
||||
|
||||
> [!NOTE]
|
||||
> Enabling virtualized GPU can potentially increase the attack surface of the sandbox.
|
||||
@ -69,20 +90,24 @@ Supported values:
|
||||
|
||||
Enables or disables networking in the sandbox. You can disable network access to decrease the attack surface exposed by the sandbox.
|
||||
|
||||
`<Networking>value</Networking>`
|
||||
```xml
|
||||
<Networking>value</Networking>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables networking in the sandbox.
|
||||
- *Disable*: Disables networking in the sandbox.
|
||||
- *Default*: This value is the default value for networking support. This value enables networking by creating a virtual switch on the host and connects the sandbox to it via a virtual NIC.
|
||||
- **Enable**: Enables networking in the sandbox.
|
||||
- **Disable**: Disables networking in the sandbox.
|
||||
- **Default**: This value is the default value for networking support. This value 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 the internal network.
|
||||
|
||||
### Mapped folders
|
||||
|
||||
An array of folders, each representing a location on the host machine that is shared with the sandbox at the specified path. At this time, relative paths aren't supported. If no path is specified, the folder is mapped to the container user's desktop.
|
||||
An array of folders, each representing a location on the host machine that is shared with the sandbox at the specified path. Currently, relative paths aren't supported.
|
||||
|
||||
When using `<Mappedfolders>` to map folders, the folders are mapped prior to the execution of the [Logon command](#logon-command).
|
||||
|
||||
```xml
|
||||
<MappedFolders>
|
||||
@ -97,12 +122,12 @@ An array of folders, each representing a location on the host machine that is sh
|
||||
</MappedFolders>
|
||||
```
|
||||
|
||||
- *HostFolder*: Specifies the folder on the host machine to share into the sandbox. The folder must already exist on the host, or the container fails to start.
|
||||
- *SandboxFolder*: Specifies the destination in the sandbox to map the folder to. If the folder doesn't exist, it is created. If no sandbox folder is specified, the folder is mapped to the container desktop.
|
||||
- *ReadOnly*: If *true*, enforces read-only access to the shared folder from within the container. Supported values: *true*/*false*. Defaults to *false*.
|
||||
- **HostFolder**: Specifies the folder on the host machine to share into the sandbox. The folder must already exist on the host, or the container fails to start.
|
||||
- **SandboxFolder**: Specifies the destination in the sandbox to map the folder to. If the folder doesn't exist, it is created. If no sandbox folder is specified, the folder is mapped to the container desktop.
|
||||
- **ReadOnly**: If *true*, enforces read-only access to the shared folder from within the container. Supported values: *true*/*false*. Defaults to *false*.
|
||||
|
||||
> [!NOTE]
|
||||
> Files and folders mapped in from the host can be compromised by apps in the sandbox or potentially affect the host.
|
||||
> Files and folders mapped in from the host can be compromised by apps in the sandbox or potentially affect the host. Changes made during a Sandbox session to a mapped folder with write-permissions will persist after a Sandbox is disposed.
|
||||
|
||||
### Logon command
|
||||
|
||||
@ -114,22 +139,24 @@ Specifies a single command that will be invoked automatically after the sandbox
|
||||
</LogonCommand>
|
||||
```
|
||||
|
||||
*Command*: A path to an executable or script inside the container that will be executed after signing in.
|
||||
**Command**: A path to an executable or script inside the container that will be executed after signing in.
|
||||
|
||||
> [!NOTE]
|
||||
> Although very simple commands will work (such as 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.
|
||||
> Although very simple commands will work (such as 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 `<LogonCommand>`.
|
||||
|
||||
### Audio input
|
||||
|
||||
Enables or disables audio input to the sandbox.
|
||||
|
||||
`<AudioInput>value</AudioInput>`
|
||||
```xml
|
||||
<AudioInput>value</AudioInput>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables audio input in the sandbox. If this value is set, the sandbox can receive audio input from the user. Applications that use a microphone may require this capability.
|
||||
- *Disable*: Disables audio input in the sandbox. If this value is set, the sandbox can't receive audio input from the user. Applications that use a microphone may not function properly with this setting.
|
||||
- *Default*: This value is the default value for audio input support. Currently, this default value denotes that audio input is enabled.
|
||||
- **Enable**: Enables audio input in the sandbox. If this value is set, the sandbox can receive audio input from the user. Applications that use a microphone may require this capability.
|
||||
- **Disable**: Disables audio input in the sandbox. If this value is set, the sandbox can't receive audio input from the user. Applications that use a microphone may not function properly with this setting.
|
||||
- **Default**: This value is the default value for audio input support. Currently, this default value denotes that audio input is enabled.
|
||||
|
||||
> [!NOTE]
|
||||
> There may be security implications of exposing host audio input to the container.
|
||||
@ -138,30 +165,32 @@ Supported values:
|
||||
|
||||
Enables or disables video input to the sandbox.
|
||||
|
||||
`<VideoInput>value</VideoInput>`
|
||||
```xml
|
||||
<VideoInput>value</VideoInput>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables video input in the sandbox.
|
||||
- *Disable*: Disables video input in the sandbox. Applications that use video input may not function properly in the sandbox.
|
||||
- *Default*: This value is the default value for video input support. Currently, this default value denotes that video input is disabled. Applications that use video input may not function properly in the sandbox.
|
||||
- **Enable**: Enables video input in the sandbox.
|
||||
- **Disable**: Disables video input in the sandbox. Applications that use video input may not function properly in the sandbox.
|
||||
- **Default**: This value is the default value for video input support. Currently, this default value denotes that video input is disabled. Applications that use video input may not function properly in the sandbox.
|
||||
|
||||
> [!NOTE]
|
||||
> There may be security implications of exposing host video input to the container.
|
||||
|
||||
### Protected client
|
||||
|
||||
When Protected Client mode is enabled, Sandbox adds a new layer of security boundary by running inside an [AppContainer Isolation](/windows/win32/secauthz/appcontainer-isolation) execution environment.
|
||||
When Protected Client mode is enabled, Sandbox adds a new layer of security boundary by running inside an [AppContainer Isolation](/windows/win32/secauthz/appcontainer-isolation) execution environment. AppContainer Isolation provides Credential, Device, File, Network, Process, and Window isolation.
|
||||
|
||||
AppContainer Isolation provides Credential, Device, File, Network, Process, and Window isolation.
|
||||
|
||||
`<ProtectedClient>value</ProtectedClient>`
|
||||
```xml
|
||||
<ProtectedClient>value</ProtectedClient>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Runs Windows sandbox in Protected Client mode. If this value is set, the Sandbox runs in AppContainer Isolation.
|
||||
- *Disable*: Runs the Sandbox in the standard mode without extra security mitigations.
|
||||
- *Default*: This value is the default value for Protected Client mode. Currently, this default value denotes that the sandbox doesn't run in Protected Client mode.
|
||||
- **Enable**: Runs Windows sandbox in Protected Client mode. If this value is set, the Sandbox runs in AppContainer Isolation.
|
||||
- **Disable**: Runs the Sandbox in the standard mode without extra security mitigations.
|
||||
- **Default**: This value is the default value for Protected Client mode. Currently, this default value denotes that the sandbox doesn't run in Protected Client mode.
|
||||
|
||||
> [!NOTE]
|
||||
> This setting may restrict the user's ability to copy/paste files in and out of the sandbox.
|
||||
@ -170,135 +199,36 @@ Supported values:
|
||||
|
||||
Enables or disables printer sharing from the host into the sandbox.
|
||||
|
||||
`<PrinterRedirection>value</PrinterRedirection>`
|
||||
```xml
|
||||
<PrinterRedirection>value</PrinterRedirection>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables sharing of host printers into the sandbox.
|
||||
- *Disable*: Disables printer redirection in the sandbox. If this value is set, the sandbox can't view printers from the host.
|
||||
- *Default*: This value is the default value for printer redirection support. Currently, this default value denotes that printer redirection is disabled.
|
||||
- **Enable**: Enables sharing of host printers into the sandbox.
|
||||
- **Disable**: Disables printer redirection in the sandbox. If this value is set, the sandbox can't view printers from the host.
|
||||
- **Default**: This value is the default value for printer redirection support. Currently, this default value denotes that printer redirection is disabled.
|
||||
|
||||
### Clipboard redirection
|
||||
|
||||
Enables or disables sharing of the host clipboard with the sandbox.
|
||||
|
||||
`<ClipboardRedirection>value</ClipboardRedirection>`
|
||||
```xml
|
||||
<ClipboardRedirection>value</ClipboardRedirection>
|
||||
```
|
||||
|
||||
Supported values:
|
||||
|
||||
- *Enable*: Enables sharing of the host clipboard with the sandbox.
|
||||
- *Disable*: Disables clipboard redirection in the sandbox. If this value is set, copy/paste in and out of the sandbox is restricted.
|
||||
- *Default*: This value is the default value for clipboard redirection. Currently, copy/paste between the host and sandbox are permitted under *Default*.
|
||||
- **Enable**: Enables sharing of the host clipboard with the sandbox.
|
||||
- **Disable**: Disables clipboard redirection in the sandbox. If this value is set, copy/paste in and out of the sandbox is restricted.
|
||||
- **Default**: This value is the default value for clipboard redirection. Currently, copy/paste between the host and sandbox are permitted under *Default*.
|
||||
|
||||
### Memory in MB
|
||||
|
||||
Specifies the amount of memory that the sandbox can use in megabytes (MB).
|
||||
|
||||
`<MemoryInMB>value</MemoryInMB>`
|
||||
```xml
|
||||
<MemoryInMB>value</MemoryInMB>
|
||||
```
|
||||
|
||||
If the memory value specified is insufficient to boot a sandbox, it is automatically increased to the required minimum amount.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1
|
||||
|
||||
The following config file can be used to easily test the downloaded files inside the sandbox. To achieve this testing, networking and vGPU are disabled, and the sandbox is allowed read-only access to the shared downloads folder. For convenience, the logon command opens the downloads folder inside the sandbox when it's started.
|
||||
|
||||
#### Downloads.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<vGpu>Disable</vGpu>
|
||||
<Networking>Disable</Networking>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\Users\Public\Downloads</HostFolder>
|
||||
<SandboxFolder>C:\Users\WDAGUtilityAccount\Downloads</SandboxFolder>
|
||||
<ReadOnly>true</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>explorer.exe C:\users\WDAGUtilityAccount\Downloads</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
```
|
||||
|
||||
### Example 2
|
||||
|
||||
The following config file installs Visual Studio Code in the sandbox, which requires a slightly more complicated LogonCommand setup.
|
||||
|
||||
Two folders are mapped into the sandbox; the first (SandboxScripts) contains VSCodeInstall.cmd, which installs and runs Visual Studio Code. The second folder (CodingProjects) is assumed to contain project files that the developer wants to modify using Visual Studio Code.
|
||||
|
||||
With the Visual Studio Code installer script already mapped into the sandbox, the LogonCommand can reference it.
|
||||
|
||||
#### VSCodeInstall.cmd
|
||||
|
||||
Downloads VS Code to `downloads` folder and runs installation from `downloads` folder.
|
||||
|
||||
```batch
|
||||
REM Download Visual Studio Code
|
||||
curl -L "https://update.code.visualstudio.com/latest/win32-x64-user/stable" --output C:\users\WDAGUtilityAccount\Downloads\vscode.exe
|
||||
|
||||
REM Install and run Visual Studio Code
|
||||
C:\users\WDAGUtilityAccount\Downloads\vscode.exe /verysilent /suppressmsgboxes
|
||||
```
|
||||
|
||||
#### VSCode.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\SandboxScripts</HostFolder>
|
||||
<SandboxFolder>C:\Users\WDAGUtilityAccount\Downloads\sandbox</SandboxFolder>
|
||||
<ReadOnly>true</ReadOnly>
|
||||
</MappedFolder>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\CodingProjects</HostFolder>
|
||||
<SandboxFolder>C:\Users\WDAGUtilityAccount\Documents\Projects</SandboxFolder>
|
||||
<ReadOnly>false</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>C:\Users\WDAGUtilityAccount\Downloads\sandbox\VSCodeInstall.cmd</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
```
|
||||
|
||||
### Example 3
|
||||
|
||||
The following config file runs a PowerShell script as a logon command to swap the primary mouse button for left-handed users.
|
||||
|
||||
`C:\sandbox` folder on the host is mapped to the `C:\sandbox` folder in the sandbox, so the `SwapMouse.ps1` script can be referenced in the sandbox configuration file.
|
||||
|
||||
#### SwapMouse.ps1
|
||||
|
||||
Create a PowerShell script using the following code, and save it in the `C:\sandbox` directory as `SwapMouse.ps1`.
|
||||
|
||||
```powershell
|
||||
[Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") | Out-Null
|
||||
|
||||
$SwapButtons = Add-Type -MemberDefinition @'
|
||||
[DllImport("user32.dll")]
|
||||
public static extern bool SwapMouseButton(bool swap);
|
||||
'@ -Name "NativeMethods" -Namespace "PInvoke" -PassThru
|
||||
|
||||
$SwapButtons::SwapMouseButton(!([System.Windows.Forms.SystemInformation]::MouseButtonsSwapped))
|
||||
```
|
||||
|
||||
### SwapMouse.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\sandbox</HostFolder>
|
||||
<SandboxFolder>C:\sandbox</SandboxFolder>
|
||||
<ReadOnly>True</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>powershell.exe -ExecutionPolicy Bypass -File C:\sandbox\SwapMouse.ps1</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
```
|
||||
|
||||
@ -24,3 +24,52 @@ sections:
|
||||
- *Test software features risk-free*: Easily test out software without the need for installing or uninstalling on your host machine.
|
||||
- *Maintaining multiple dev environments*: Streamline your development process by utilizing WSB to maintain multiple sandboxes for different development environments
|
||||
- *Privacy Protection*: Users concerned about online privacy can use Windows Sandbox for activities like social media browsing or online shopping to prevent tracking cookies and other privacy-invading techniques.
|
||||
|
||||
- question: What's the difference between a Hyper-V VM and Windows Sandbox?
|
||||
answer: |
|
||||
1. **Lightweight and Temporary**:
|
||||
- **Windows Sandbox**: It's a lightweight, disposable environment that runs within your existing Windows installation. You can quickly launch it, test applications, and discard it without affecting your main system.
|
||||
- **Hyper-V VMs**: Hyper-V VMs are more heavyweight. They require dedicated resources (CPU, memory, disk space) and take longer to set up.
|
||||
1. **Security Isolation**:
|
||||
- **Windows Sandbox**: Provides a secure, isolated environment for testing untrusted software. Any changes made within the sandbox are discarded when you close it.
|
||||
- **Hyper-V VMs**: While VMs also offer isolation, they persistently store changes unless you revert them manually.
|
||||
1. **Resource Efficiency**:
|
||||
- **Windows Sandbox**: More resource efficient than full VM. It adjusts memory usage according to the demand. It also reuses many of the host’s read only OS files.
|
||||
- **Hyper-V VMs**: VMs have fixed resource allocations, which can impact overall system performance.
|
||||
1. **Ease of Use**:
|
||||
- **Windows Sandbox**: Simple to use—just open it, test your software, and close it. No complex setup or management.
|
||||
- **Hyper-V VMs**: Require more configuration, including setting up virtual switches, network adapters, and managing VM snapshots.
|
||||
|
||||
- question: Why can I not change certain settings using a config file?
|
||||
answer: |
|
||||
You cannot make changes to properties if they are controlled by Group Policy. Contact your IT Administrator for more details.
|
||||
|
||||
- question: How do I open multiple Sandbox instances?
|
||||
answer: |
|
||||
Today, Windows Sandbox only allows users to launch one Sandbox instance at a time.
|
||||
|
||||
- name: Feedback
|
||||
questions:
|
||||
|
||||
- question: Where can I provide feedback?
|
||||
answer: |
|
||||
You can file a bug in Feedback Hub by:
|
||||
|
||||
1. Open the Feedback Hub app.
|
||||
1. Select **Report a problem** or **Suggest a feature**.
|
||||
1. Fill in the **Summarize your feedback** and **Explain in more details** boxes with a detailed description of the issue or suggestion. A useful feedback item includes the following:
|
||||
- Short and descriptive issue title.
|
||||
- Windows version and build number. This can be gathered from the CMD prompt using the `cmd.exe --version`` command.
|
||||
- Device information (including CPU type, memory, disk etc.)
|
||||
- Detailed repro steps. What steps do we need to take to reproduce the issue? Provide as much detail as you can. Provide error message text where possible or screenshots of errors if text cannot be captured.
|
||||
- Behavior you were expecting.
|
||||
1. Select an appropriate category and subcategory by using the dropdown menus. There is a dedicated option in Feedback Hub to file **Windows Sandbox** bugs and feedback. It is located under **Security and Privacy** category.
|
||||
1. Select **Next**.
|
||||
1. If necessary, you can collect traces for the issue as follows: Select the Recreate my problem tile, then select Start capture, reproduce the issue, and then select **Stop capture**.
|
||||
1. Attach any relevant screenshots or files for the problem, then select **Submit**.
|
||||
|
||||
Alternatively, you can also use the [Windows Sandbox GitHub repository](https://github.com/microsoft/Windows-Sandbox) to:
|
||||
|
||||
- **Search existing issues** to see if there are any associated with a problem that you are having. Note that in the search bar, you can remove "is:open" to include issues that have already been resolved in your search. Please consider commenting or giving a thumbs up to any open issues that you would like to express your interest in moving forward as a priority.
|
||||
- **File a new issue**: If you have found a problem with WSB or WSB documentation and there does not appear to be an existing issue, you can select the green New issue button and then choose WSB - Bug Report. You will need to include a title for the issue, your Windows build number (run cmd.exe /c ver to see your current build #), whether you're running inbox or undocked Windows Sandbox, any other software versions involved, the repro steps, expected behavior, actual behavior, and diagnostic logs if available and appropriate.
|
||||
- **File a feature request** by selecting the green New issue button and then select Feature request. You will need to address a few questions describing your request.
|
||||
|
||||
@ -16,12 +16,11 @@ ms.date: 09/09/2024
|
||||
- At least two CPU cores (four cores with hyper-threading recommended)
|
||||
|
||||
> [!NOTE]
|
||||
> Windows Sandbox is currently not supported on Windows Home edition.
|
||||
> Beginning in Windows 11, version 24H2, all inbox store apps like calculator, photos, notepad and terminal are not available inside Windows Sandbox. Ability to use these apps will be added soon.
|
||||
> Beginning in Windows 11, version 24H2, inbox store apps like Calculator, Photos, Notepad and Terminal are not available inside Windows Sandbox. Ability to use these apps will be added soon.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Ensure that your machine is using Windows 10 Pro or Enterprise, build version 18305 or Windows 11.
|
||||
1. Ensure that your machine is using Windows 11 or Windows 10, version 1903 or later.
|
||||
|
||||
2. Enable virtualization on the machine.
|
||||
|
||||
@ -50,3 +49,11 @@ ms.date: 09/09/2024
|
||||
> Beginning in Windows 11, version 24H2, Windows Sandbox adheres to the mouse settings of the host system.
|
||||
>
|
||||
> If you are on an older build and if the host system is set to use a left-handed mouse, you must apply these settings in Windows Sandbox manually when Windows Sandbox starts. Alternatively, you can use a sandbox configuration file to run a logon command to swap the mouse setting. For an example, see [Example 3](windows-sandbox-configure-using-wsb-file.md#example-3).
|
||||
|
||||
## Try WSB preview features by joining the Windows Insider Program
|
||||
|
||||
To try the most recent features or updates to WSB, join the [Windows Insiders Program](https://insider.windows.com/getting-started). Once you have joined Windows Insiders, you can choose the channel you would like to receive preview builds from inside the Windows settings menu. You can choose from:
|
||||
|
||||
- **Dev channel**: Most recent updates, but low stability.
|
||||
- **Beta channel**: Ideal for early adopters, more reliable builds than the Dev channel.
|
||||
- **Release Preview channel**: Preview fixes and key features on the next version of Windows just before its available to the general public.
|
||||
|
||||
@ -1,31 +1,44 @@
|
||||
---
|
||||
title: Windows Sandbox
|
||||
description: Windows Sandbox overview
|
||||
ms.topic: conceptual
|
||||
ms.topic: overview
|
||||
ms.date: 09/09/2024
|
||||
---
|
||||
|
||||
# Windows Sandbox
|
||||
|
||||
Windows Sandbox provides a lightweight desktop environment to safely run applications in isolation. Software installed inside the Windows Sandbox environment remains "sandboxed" and runs separately from the host machine.
|
||||
Windows Sandbox (WSB) offers a lightweight, isolated desktop environment for safely running applications. It is ideal for testing, debugging, exploring unknown files, and experimenting with tools. Applications installed within the sandbox remain isolated from the host machine using hypervisor-based virtualization. As a disposable virtual machine (VM), Windows Sandbox ensures reboot persistence, quick launch times, and a lower memory footprint compared to full VMs. Its one-click setup simplifies the user experience.
|
||||
|
||||
A sandbox is temporary. When it's closed, all the software and files and the state are deleted. You get a brand-new instance of the sandbox every time you open the application. Note, however, that as of Windows 11, version 22H2, your data persists through a restart initiated from inside the virtualized environment—useful for installing applications that require the OS to reboot.
|
||||
The sandbox is temporary; closing it deletes all software, files, and state. Each launch provides a fresh instance. Host-installed software isn't available in the sandbox. Applications needed within the sandbox must be installed there explicitly.
|
||||
|
||||
Software and applications installed on the host aren't directly available in the sandbox. If you need specific applications available inside the Windows Sandbox environment, they must be explicitly installed within the environment.
|
||||
> [!NOTE]
|
||||
> Starting with Windows 11, version 22H2, data persists through restarts initiated within the sandbox, useful for applications requiring a reboot.
|
||||
|
||||
Windows Sandbox has the following properties:
|
||||
Windows Sandbox offers the following features:
|
||||
|
||||
- **Part of Windows**: Everything required for this feature is included in Windows 10 Pro and Enterprise. There's no need to download a Virtual Hard Disk (VHD).
|
||||
- **Pristine**: Every time Windows Sandbox runs, it's as clean as a brand-new installation of Windows.
|
||||
- **Part of Windows**: Everything required for this feature is included in the supported Windows SKUs like Pro, Enterprise and Education. There's no need to maintain a separate VM installation.
|
||||
- **Disposable**: Nothing persists on the device. Everything is discarded when the user closes the application.
|
||||
- **Pristine**: Every time Windows Sandbox runs, it's as clean as a brand-new installation of Windows.
|
||||
- **Secure**: Uses hardware-based virtualization for kernel isolation. It relies on the Microsoft hypervisor to run a separate kernel that isolates Windows Sandbox from the host.
|
||||
- **Efficient:** Uses the integrated kernel scheduler, smart memory management, and virtual GPU.
|
||||
- **Efficient**: Takes a few seconds to launch, supports virtual GPU and has smart memory management that optimizes memory footprint.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Windows Sandbox enables network connection by default. It can be disabled using the [Windows Sandbox configuration file](windows-sandbox-configure-using-wsb-file.md#networking).
|
||||
> Windows Sandbox enables network connection by default. It can be disabled using the [Windows Sandbox configuration file](windows-sandbox-configure-using-wsb-file.md#networking). Enabling networking can expose untrusted applications to the internal network.
|
||||
|
||||
WSB can be used by anyone without any technical skills in various scenarios where users need a secure, clean environment for testing or running potentially harmful software. Here are some ways in which you can leverage WSB:
|
||||
|
||||
- **Clean environment for software testing**: Test or debug your applications in WSB's clean environment to identify and resolve bugs or compatibility issues.
|
||||
- **Secure web browsing**: Use WSB for secure web browsing, especially when accessing unfamiliar or potentially dangerous websites without putting your system at risk of malware infection.
|
||||
- **Running Untrusted Applications**: Mitigate security risks by opening untrusted applications or files, such as email attachments in WSB. Improve your safety and security by opening a sandbox with networking disabled and mapping the folder with the application or file you want to open to the sandbox in read-only mode. Check [Sample configuration files](windows-sandbox-sample-configuration.md) for more details.
|
||||
- **Testing or demoing new software for the first time**: Test drive or demo new software, unstable versions like beta, extensions or add-ons without the hassle of installing and then uninstalling on your host machine.
|
||||
- **Maintaining multiple dev environments**: Streamline your development process by utilizing WSB to maintain multiple sandboxes for different development environments. For example, maintain a sandbox for each python version and its dependencies!
|
||||
|
||||
|
||||
[!INCLUDE [windows-sandbox](../../../../../includes/licensing/windows-sandbox.md)]
|
||||
|
||||
> [!NOTE]
|
||||
> Windows Sandbox is currently not supported on Windows Home edition.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Copy an executable file (and any other files needed to run the application) from the host and paste them into the **Windows Sandbox** window.
|
||||
|
||||
@ -6,3 +6,107 @@ ms.date: 09/09/2024
|
||||
---
|
||||
|
||||
# Windows Sandbox sample configuration files
|
||||
|
||||
## Example 1 - Mapping Folders and testing an unknown downloaded file in a Sandbox
|
||||
|
||||
The following config file can be used to easily test unknown downloaded files inside a sandbox. To achieve this testing, networking and vGPU are disabled, and the sandbox is allowed read-only access to the downloads folder from the host and is placed inside a 'temp' folder in the sandbox. For convenience, the logon command opens the downloads folder inside the sandbox when it's started.
|
||||
|
||||
### Downloads.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<VGpu>Disable</VGpu>
|
||||
<Networking>Disable</Networking>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\Users\Public\Downloads</HostFolder>
|
||||
<SandboxFolder>C:\temp</SandboxFolder>
|
||||
<ReadOnly>true</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>explorer.exe C:\temp</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
|
||||
```
|
||||
|
||||
## Example 2 - Installing Visual Studio Code at launch in a Sandbox
|
||||
|
||||
The following config file installs Visual Studio Code in the sandbox, which requires a slightly more complicated LogonCommand setup.
|
||||
|
||||
Two folders are mapped into the sandbox; the first (`SandboxScripts`) contains VSCodeInstall.cmd, which installs and runs Visual Studio Code. The second folder (`CodingProjects`) is assumed to contain project files that the developer wants to modify using Visual Studio Code.
|
||||
|
||||
With the Visual Studio Code installer script already mapped into the sandbox, the `<LogonCommand>` can reference it.
|
||||
|
||||
### VSCodeInstall.cmd
|
||||
|
||||
This batch file should be created in the `C:\SandboxScripts` directory on the host. It downloads VS Code to `temp` folder inside the sandbox and runs installation from `temp` folder.
|
||||
|
||||
```batch
|
||||
REM Download Visual Studio Code
|
||||
curl -L "https://update.code.visualstudio.com/latest/win32-x64-user/stable" --output C:\temp\vscode.exe
|
||||
|
||||
REM Install and run Visual Studio Code
|
||||
C:\temp\vscode.exe /verysilent /suppressmsgboxes
|
||||
```
|
||||
|
||||
### VSCode.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\SandboxScripts</HostFolder>
|
||||
<SandboxFolder>C:\temp\sandbox</SandboxFolder>
|
||||
<ReadOnly>true</ReadOnly>
|
||||
</MappedFolder>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\CodingProjects</HostFolder>
|
||||
<SandboxFolder>C:\temp\Projects</SandboxFolder>
|
||||
<ReadOnly>false</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>C:\temp\sandbox\VSCodeInstall.cmd</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
```
|
||||
|
||||
## Example 3 - Mapping Folders and running a PowerShell script as a LogOn Command
|
||||
|
||||
The following config file runs a PowerShell script as a logon command to swap the primary mouse button for left-handed users.
|
||||
|
||||
`C:\sandbox` folder on the host is mapped to the `C:\sandbox` folder in the sandbox, so the `SwapMouse.ps1` script can be referenced in the sandbox configuration file.
|
||||
|
||||
### SwapMouse.ps1
|
||||
|
||||
Create a PowerShell script using the following code, and save it in the `C:\sandbox` directory as `SwapMouse.ps1`.
|
||||
|
||||
```powershell
|
||||
[Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") | Out-Null
|
||||
|
||||
$SwapButtons = Add-Type -MemberDefinition @'
|
||||
[DllImport("user32.dll")]
|
||||
public static extern bool SwapMouseButton(bool swap);
|
||||
'@ -Name "NativeMethods" -Namespace "PInvoke" -PassThru
|
||||
|
||||
$SwapButtons::SwapMouseButton(!([System.Windows.Forms.SystemInformation]::MouseButtonsSwapped))
|
||||
```
|
||||
|
||||
### SwapMouse.wsb
|
||||
|
||||
```xml
|
||||
<Configuration>
|
||||
<MappedFolders>
|
||||
<MappedFolder>
|
||||
<HostFolder>C:\sandbox</HostFolder>
|
||||
<SandboxFolder>C:\sandbox</SandboxFolder>
|
||||
<ReadOnly>True</ReadOnly>
|
||||
</MappedFolder>
|
||||
</MappedFolders>
|
||||
<LogonCommand>
|
||||
<Command>powershell.exe -ExecutionPolicy Bypass -File C:\sandbox\SwapMouse.ps1</Command>
|
||||
</LogonCommand>
|
||||
</Configuration>
|
||||
```
|
||||
@ -6,3 +6,4 @@ ms.date: 09/09/2024
|
||||
---
|
||||
|
||||
# Troubleshoot Windows Sandbox
|
||||
|
||||
|
||||
Reference in New Issue
Block a user