Whonix gives you Tor isolation by routing one VM's traffic through another. Gateway VM handles Tor. Workstation VM does the actual work. If the Workstation gets compromised, your real IP doesn't leak because it can only talk to the Gateway.
Setting it up by hand is tedious. Download VirtualBox, download two OVA files, import them, configure network adapters, allocate RAM, disable USB and audio, boot Gateway, wait for Tor, then boot Workstation. Miss a step and your isolation is broken.
I wrote a PowerShell project that does the whole thing.
What it actually does
Four scripts run in order:
.\prereq-check.ps1
.\setup.ps1
.\configure-vms.ps1
.\start-whonix.ps1
prereq-check.ps1 validates RAM, CPU cores, disk space, and whether VT-x or AMD-V is enabled. It fails fast if your machine can't run two VMs.
setup.ps1 pulls the right VirtualBox version and the two Whonix OVAs (Gateway and Workstation), then verifies SHA-512 hashes before importing. If a download is tampered with mid-flight, the install stops there.
configure-vms.ps1 sets the security defaults. USB controllers off, audio off, 3D acceleration off, nested virtualization off. Clipboard isolation between host and guest. Gateway gets a fixed 1 CPU and 1 GB of RAM because Tor doesn't need more, and giving it more is wasted memory. Workstation gets 25 to 40 percent of available RAM depending on what the host can spare.
start-whonix.ps1 boots Gateway first, then waits.
The startup ordering thing
This is the part that took the longest to get right.
You can't just boot both VMs at once. The Workstation has its only network route through the Gateway. If the Workstation comes up before Tor finishes bootstrapping inside the Gateway, the Workstation has no DNS, no connectivity, nothing. Some apps will time out and stay broken until you restart them.
My first attempt was a hardcoded sleep. Wait 90 seconds after starting Gateway, then start Workstation. It worked on my fast machine. On a slower one it didn't. Sometimes Tor took 3 minutes to bootstrap.
The fix was to poll. After Gateway boots, the script opens a TCP connection to the Gateway's Tor SocksPort. If it connects, Tor is ready. If it refuses or hangs, keep waiting. There's a timeout at 5 minutes because if Tor hasn't bootstrapped by then something else is wrong.
The check is dumb but reliable:
$tcpClient = New-Object System.Net.Sockets.TcpClient
$connect = $tcpClient.BeginConnect($gatewayIP, 9050, $null, $null)
$wait = $connect.AsyncWaitHandle.WaitOne(2000, $false)
if ($wait -and $tcpClient.Connected) { return $true }
Wrapped in a retry loop with a small delay between attempts.
Version pinning
The other thing I wanted was reproducibility. If I deploy this on three machines, I want the exact same VirtualBox version and the exact same Whonix images on all of them.
Whonix releases change. So does VirtualBox. So the script takes pinned version parameters with their expected hashes:
.\setup.ps1 -WhonixVersion "18.1.4.2" -WhonixHash "sha512:abc..."
If you don't pass them, it uses a default set that's known to work. If you pass a version, you also pass the hash, and the script refuses to run if the download doesn't match. This is annoying when versions change because I have to update the defaults. But it means a stale clone of the repo won't silently pull a different image.
Security defaults
A lot of the configure step is just turning things off. USB passthrough off, because a compromised workstation shouldn't be able to read your USB drives. Audio off, same reason. 3D acceleration off, because the graphics passthrough has had escape bugs before. Nested virtualization off, because the Workstation shouldn't be spinning up its own VMs.
Clipboard sharing is set to host-to-guest only, not bidirectional. Drag and drop is disabled. Shared folders are not configured by default. If you want any of these you have to turn them on yourself, which is the point.
None of this is novel. The Whonix docs recommend most of these settings. The script just makes sure I don't forget one.
What's still broken
It only works on Windows. The PowerShell is everywhere but VBoxManage paths and registry checks are Windows-specific. Linux users have their own tooling for this already.
It doesn't handle the case where VirtualBox is already installed but with a mismatched version. Right now it just warns. I should add a flag to force-upgrade or skip.
And the prerequisites check is conservative. It refuses to run on machines with less than 8 GB of RAM, but Whonix technically runs on 4 GB if you're patient. Someone with a low-end machine asked me to add an override and I haven't yet.
Repo
github.com/TiltedLunar123/WhonixAutoSetup
The README has the full parameter list and a few troubleshooting notes for when the Tor bootstrap fails. If you run it and something breaks, the issue tracker is open.
Top comments (0)