kistaro/windows-sandbox-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

write documentation

Browse Source
This commit is contained in:
Kistaro Windrider 2025-03-01 12:25:27 -08:00
parent 4457246008
commit 319ac65e3d
Signed by: kistaro
SSH Key Fingerprint: SHA256:TBE2ynfmJqsAf0CP6gsflA0q5X5wD5fVKWPsZ7eVUg8
1 changed files with 100 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@ -1,3 +1,102 @@
# windows-sandbox-config
Ready-to-use Windows Sandbox configurations for running random software without putting the rest of your computer and data at risk -- useful for things like game jams.
Ready-to-use Windows Sandbox configurations for running random software without putting the rest of your computer and data at risk -- useful for things like game jams.
## Overview
### What is Windows Sandbox? Why would I use it?
Windows Sandbox is a lightweight, temporary virtual machine system provided by Microsoft for users of the Pro, Enterprise, and Education versions of Windows 10 and 11. It relies on Microsoft Hyper-V, so you'll need a computer and OS capable of that (and configured to enable it).
A virtual machine is like a separate computer. Windows Sandbox, specifically, is computer you intend to throw away! This lets you run software you don't trust (because it might be malware, might have a virus, might accidentally delete all your files because of a bug, etc.) relatively safely. Because it _doesn't_ save its work from run to run -- it's like a new computer each time -- you'd need to use something else for a program you intend to use a lot, but it's great for experimenting or running things only once -- for example, when you're trying to rate 89 games in two weeks for a game jam.
### What's this repository for?
Windows Sandbox can be inconvenient to configure. Its default configuration doesn't make it obvious how to get files "into" the sandbox and you have to look around for its help documentation. This repository contains a folder intended to be used as the start of a sandbox: it has a couple of subfolders for getting stuff into (and, if you feel brave, out of) the sandbox, configurations to set up those folders, and a script to make the sandbox actually willing to run software (which you'd think would be on by default...). Windows Sandbox only takes _one_ script as a logon command, so this repository includes a batch file you can add other boot commands to, even though right now it only calls one other script that could have been the logon command itself.
This repository is convenient for experienced Windows admins and intended to be ready-to-use as-is for folks who aren't so experienced.
## Getting Started
### Windows Sandbox setup
Windows Sandbox requires a computer with hardware virtualization features and a version of Windows that lets you use them -- the "Pro"-type versions. If you've got that, you can just turn on Windows Sandbox in the "turn Windows features on or off" thing.
To set up Windows Sandbox, follow [Microsoft's instructions.](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-install)
You might need to reboot your computer, hold down some button to go into BIOS settings, and enable virtualization features (which might be called "Hyper-V", might be called something else). You _might_ be able to get there by holding a `Shift` key while rebooting your computer from the Start menu (Start > power options > ⇧ + Restart), which will reboot your computer into an "advanced startup" menu. Not all computers make the BIOS settings reachable from that menu; look for some kind of "press \<something\> to enter setup" message during boot to figure out how to get there instead, or look up the instruction manual for your computer or your computer's motherboard.
### Initial configuration
1. Either download the .zip file from the "Releases" tab and extract it somewhere you want to use as the basis of a sandbox, or use Git to clone this repository somewhere.
2. If your computer has less than 12GB of RAM, use your text editor of choice (Notepad works but you probably have something better) to edit each of the `.wsb` files (right click, "Open With..." to get these into a text editor, a double-click will just launch the sandbox). Look for the number after `<MemoryInMB>` (8192, the way I have it specified by default), replace it with 4096, and save the file. Do this for both `.wsb` files. If you have more than 16GB of RAM and you're trying to run demanding software in the sandbox, you might want to use a larger number instead (16384 might be a good choice for a machine with 32GB of RAM).
3. Copy any software you want to run into the `SandboxInput` folder.
### Use
1. Double-click `readonly-SandboxInput.wsb`. Windows Sandbox should launch, bringing up a window showing the default Windows desktop, with a folder named "SandboxInput" on the Desktop.
2. Double-click the `SandboxInput` folder in the Sandbox to open it. You should see everything you copied into `SandboxInput` (plus the `LogonScripts` directory included in the repository).
3. Run anything you want.
The software should launch. When you're done using it, close Windows Sandbox. There's no reason to shut it down politely via the Start Menu, because the sandbox will cease to exist after it shuts down, so it doesn't matter if it shuts down cleanly or not, it will never be rebooted again anyway; if you start Windows Sandbox again with the same files, it is starting over with a new computer.
SandboxInput is _read-only_ in the sandbox. If you need to save files, save them somewhere else and they'll last until you close the sandbox. If you really need to save files across multiple runs of the sandbox, use `readSandboxInput-rwSandboxPersist.wsb` when launching the sandbox, and there will be a second folder on the desktop, `SandboxPersist`. This is a view of the `SandboxPersist` folder in the repository (which starts out with a meaningless text file, just so Git knows the folder is there), which is mounted _read-write_ so the Sandbox can save it. **This mode writes real files to your real computer** so it is riskier than the read-only mode -- don't use the files you save in the sandbox _outside_ of the sandbox unless you are adequately sure the software inside the sandbox never really needed to be sandboxed in the first place! When you use this version of the sandbox again, it's still a new computer, but it will reuse the same `SandboxPersist` folder so those files will exist again in the new sandbox and you can use them again.
If you want to keep game data across sandbox restarts that is written to your Application Data directory or something, you'll have to copy it by hand or set up another mapping specifically to grab and persist the user profile. This is more complicated; you'll need to modify the folder mappings in the config files I provided to set this up. (I might write a config that does this for you in a later version.)
## Troubleshooting / FAQ
### I can't find Windows Sandbox when I try to install it.
You probably have the Home edition of Windows. Windows Sandbox requires Pro. Sorry.
Sandbox is based on Hyper-V,which is one of Microsoft's core holdbacks for Pro -- if you want to use the high-performance virtualization system they spent hundreds millions of dollars developing, they want you to pay them for it.
### I exited the sandbox, restarted it, and everything is gone! What happened?
The sandbox is temporary. That's supposed to happen. The entire point is that this is a computer you throw away when you're done with it, so it's okay if that computer gets a virus.
If you need to save some files, use the `readSandboxInput-rwSandboxPerist.wsb` file to launch the sandbox and save the files you want to keep into `SandboxPersist`. That folder will show up again in the Sandbox later.
### A game won't launch.
That's unfortunate. It will need troubleshooting like a failed launch on a normal computer.
In all likelihood, the software relies on your computer already having something else installed, which the sandbox did not include. There's a lot of stuff your computer probably already has -- some of which is ordinarily installed with most Windows systems -- that the sandbox doesn't start out with, so you may need to go install pieces you thought you already had. (Because you _did_ already have them, but this extra little throwaway computer doesn't.)
The .NET runtime, the Java Runtime environment, and assorted generations of Visual C++ redistributables are likely candidates here. Take a guess as to what's missing, find an installer for the missing piece, dump that into SandboxInput, and install the thing on the sandbox. You'll have to reinstall it every time you start the sandbox and need to run a program with this dependency.
If you're handy with batch files, after you get a common dependency installer in SandboxInput, you might want to edit `SandboxInput/LogonScripts/logon.bat` to tell Windows Sandbox to run this installer immediately when it starts up. (Be sure to give the Sandbox a minute or two after it boots up before trying to run stuff if you do this, so the installers have time to finish.)
### Microsoft's documentation says copy-and-paste should work to get files or text in and out of the sandbox, but it doesn't. What's going on? How can I fix it?
Microsoft sure does say that! For some reason, they thought that it would be a good idea to enable that feature by default. I think they are wrong. The configuration files I have written do not allow clipboard sharing.
You probably don't want to do this and it increases the risk of something "escaping the sandbox", but if you really need clipboard sharing, edit the `.wsb` file and change `<ClipboardRedirection>false</ClipboardRedirection>` to `<ClipboardRedirection>true</ClipboardRedirection>`.
### This online game doesn't work.
I configured the sandbox to not have any connection to the Internet. Change `<Networking>Disable</Networking>` to `<Networking>Enable</Networking>` in the `.wsb` file and it will be connected next time you start up the sandbox with that file. You might want to save this version as a separate `.wsb` so you don't connect all the _other_ random untrusted software you want to run to your network, too.
Connecting stuff to your local network increases the attack surface massively -- the software might be able to escape the sandbox by exploiting bugs in any program accepting LAN connections anywhere on your home network. Only do this if you would genuinely be willing to run the program without the sandbox anyway.
For some reason, Microsoft's default configuration enables networking. Microsoft's default configuration is very bad.
### Hey! I was using the read-write sandbox and suddenly my virus scanner said there's a virus in SandboxPersist! You gave me a virus, you bastard!
Your virus scanner is probably right! If this happens, **Windows Sandbox has just saved your real computer from running a virus.** Because the sandbox was allowed to change some real files on your real computer (the SandboxPersist folder), something that looked like a virus made it to your real computer where your virus scanner noticed and got offended, probably for good reason.
**Close the sandbox** and let your virus scanner destroy the infected file(s). You should probably delete and recreate `SandboxPersist` unless it has other stuff you really can't live without.
**Never use a read-write sandbox again with the software you were running when the virus scanner warning appeared.** It would be a good idea to never use that software again at all, because your virus scanner is very, very suspicious of how that software behaved when you ran it in a virtual machine and a little tiny slice of its behavior escaped into your real computer (so it could save files between runs).
If you're pretty sure the developer of the software you ran is not evil, you should probably talk to them about this. If you don't know them or think they might be evil, you should talk to an administrator of whereever you got the software from and ask them to take a look -- someone might need ye olde banhammer.
## Advanced Use
If you're already experienced with Windows administration (or at least "power user" configuration), you can use this as a template to configure a sandbox in more detail.
### disable_smartscreen.ps1
That PowerShell script disables Windows SmartScreen, that pointless "hey, are you sure?" dialog box that comes up whenever you try to run unsigned software, replacing it with a _different_ "hey, are you sure? this software isn't signed" dialog box instead. Well, the first one connects to the Internet and isn't installed in the Sandbox by default, while the second one is part of Windows and runs locally.
Without shutting off SmartScreen, trying to run unsigned software in the Sandbox (and let's face it, it's all unsigned) will get a bizarre-seeming "go to the Windows Store to find an app to open this file?" because it wants to use SmartScreen but doesn't _have_ it so you get an error like trying to open any other file it's missing a handler for, even though the file is a _program_ you just want to execute.
### logon.bat
It's a one-liner that just runs `disable_smartscreen`, but I added it as a convenient spot to add more launch scripts. Windows Sandbox only lets you run _one_ logon command. I initially pointed it to just `disable_smartscreen.ps1` itself (with a suitable PowerShell command), but I realized the most obvious thing a normal person would do when trying to add more logon commands is to add another `<Command>` stanza to the `<LogonCommand>` element and _that doesn't actually work._ I know this because I tried it. LogonCommand is singular. So I added a batch file to make a different thing the most obvious thing to do.
Remember, this batch file will run in the sandbox, so paths specified will be relative to the sandbox's file system.
### Windows Sandbox configuration
The only way to configure Windows Sandbox is to handwrite a `.wsb` file. [Microsoft's docs](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-configure-using-wsb-file) describe what you can do with these. Feel free to use mine as a starting point, or write a new one, or whatever.
The configuration I chose is intended for game jam games: unlikely to have any legitimate reason to touch your microphone, webcam, or network, but it probably needs your GPU to not run absolutely terribly. I also think a read-only mapped folder is a _much_ safer choice than clipboard integration for actually getting stuff into the sandbox, and I didn't want to allow any way to get stuff back _out_ of the sandbox in the standard configuration because, like, the sandbox is a nuclear waste containment zone, if you're rooting through your housecat's sandbox hunting for treasure you might be looking in the wrong spot.