Boot a Windows sandbox, install Minecraft Java Edition, and drive it with an agent through the cua-driver MCP server running inside the sandbox.
Minecraft exercises almost everything a Windows sandbox can do: it needs internet access, a Java runtime, working OpenGL, and a GUI that only clicks can drive. This guide boots a Windows sandbox, installs Minecraft Java Edition, and hands it to an agent that talks to cua-driver's MCP server inside the sandbox — the same loop against a local sandbox and against Fleet.
Before you start# #
cua-sandbox 0.3.3 or newer. Windows on Fleet needs 0.3.0,Image.expose()
on the local QEMU runtime landed in 0.3.1, thesb.exposed_ports
this guide reads the forwarded port from landed in 0.3.2, and 0.3.3 brought bothImage.from_registry(..., os_type=...)
and the pull-secret fix that lets Fleet boot an image from a registry outside its own allowlist — which the containerDisk section below needs.A host with hardware virtualisation for the local path — a Linux x86_64 machine with/dev/kvm
, or an Intel Mac. This guide passes-cpu host
, which QEMU only accepts with KVM or HVF. An x86_64 guest on Apple Silicon runs under TCG emulation, where-cpu host
is rejected outright. The Fleet path runs there instead, including the game, with the one extra environment variable described in the Fleet section below.A Microsoft account that owns Minecraft Java Edition. Signing in uses Microsoft device authorization, so one step in the middle is manual: a code appears inside the sandbox and you approve it in your own browser.A vision-capable LLM endpoint for the agent loop.
## Boot a Windows sandbox[#](#boot-a-windows-sandbox)
`Image.windows()`
resolves to a pinned Windows Server 2022 containerDisk. Three things get added on top of the defaults:
publishes cua-driver's MCP server, which already runs inside the guest, so the agent can reach it..expose(3000)
A second network interface. The bare-metal runtime attaches its NIC withrestrict=on
, which isolates the guest.sb.shell.run()
still works over the forwarded port, but nothing inside Windows can reach the internet — and Minecraft needs to.The default-cpu host
.qemu64
model is too thin for a software OpenGL driver: Minecraft creates its window and then dies while resources, with no Java exception and no crash log. The last-cpu
on the command line wins, so appending it is enough.
A warm boot takes about 30 seconds. exposed_ports
maps each exposed guest port to the host port it landed on, and GET /healthz
on that port answers ok
once cua-driver is up.
Read the port from sb.exposed_ports, not from a tunnel.
sb.tunnel.forward(3000)
— the usual way to get a forwarded port, and the one the Fleet section below uses — raises NotImplementedError: HTTPTransport does not support port forwarding
on the local transport. exposed_ports
is the local equivalent: the runtime picks a free host port at boot, so the mapping is only knowable at runtime, and it is saved with the sandbox state so a later Sandbox.connect()
can read it back. On Fleet the property is empty, because Fleet publishes services instead — use tunnel.forward()
there.Give the second NIC its own subnet. Both user-mode networks default to 10.0.2.0/24
and both offer the guest 10.0.2.15
, so Windows drops one interface to a 169.254.x.x
link-local address with no gateway and no working DNS.
Confirm the guest really has internet before installing anything.
Install a launcher and a software OpenGL driver# #
The sandbox GPU is the Microsoft Basic Display Adapter, which offers OpenGL 1.1. Minecraft 1.17 and later need OpenGL 3.2, so the game needs Mesa3D's opengl32.dll
(llvmpipe), which implements OpenGL in software.
Both downloads below are MinGW builds on purpose. The MSVC builds of Prism Launcher and Mesa both depend on the Visual C++ redistributable, which Windows Server 2022 does not ship: Prism then exits silently, and Mesa's DLL fails to load so Windows quietly falls back to the system opengl32.dll
.
Save that as setup.ps1
, push it into the sandbox, and run it. It downloads roughly 100 MB, so allow a generous timeout.
Sign in and create an instance# #
Prism opens a Quick Setup wizard on first run. Screenshot the sandbox, click through it, and stop at the account page.
- Work through the wizard to
Accounts → Add Microsoft. Prism shows a QR code and an eight-character device code. - Read the code off a screenshot, open
https://www.microsoft.com/link
in your own browser, enter it, and approve the sign-in. The account then appears with statusReady. - Click
Add Instance, search for a version such as1.20.1
, and clickOK. Prism downloads the client jar and assets.
Device codes expire after about fifteen minutes, but Prism issues a fresh one automatically and keeps polling, so the dialog can be left open. Take a new screenshot to read the current code rather than reusing an old one.
Point the software driver at the launcher's Java# #
Click Launch once. Prism downloads its own Java runtime and the game fails with GLFW error 65542: WGL: The driver does not appear to support OpenGL
— expected, because Mesa is not in place yet.
Prism may keep using the runtime it downloaded even if you set JavaPath
in its config, so copy the Mesa DLLs next to every javaw.exe
under the install root. Windows loads opengl32.dll
from the running executable's directory before the system directory, which is what makes this work. Deliver it the same way as the first script.
Click Launch again. The Minecraft title screen appears after a minute or two.
Drive it with an agent over MCP# #
The sandbox already runs cua-driver, which serves an MCP endpoint on guest port 3000 — that is what .expose(3000)
published. The agent is a small loop: list the MCP tools, hand them to a model as ordinary function tools, call whichever one it picks, feed the result back.
Three things about cua-driver's tools shape the loop:
A YAML policy governs which tools may actually run, and Every cua-driver release to date advertises the full surface and refuses out-of-policy calls only when you make them, withlist_tools()
does not reflect it.Permission denied: user policy: tool 'X' is not allowed by the YAML policy
. So the listing is a menu of what exists, not of what you can call. Here that surface was 55 tools, identically over the local and Fleet transports:get_desktop_state
,list_apps
,list_windows
,get_window_state
,click
,double_click
,type_text
,press_key
,hotkey
,launch_app
,bring_to_front
,scroll
anddrag
ran, whileget_screen_size
,get_accessibility_tree
,get_config
,check_permissions
,get_cursor_position
andzoom
were refused. Treat that split as something to probe on your own image rather than a fixed list — a denial arrives before the tool executes, so probing is cheap. Later drivers filter the listing through the policy, at which point the two finally agree.Clicks are addressed to an application, not the screen.click(pid=..., x=..., y=...)
targets a window belonging to that pid, which you find withlist_windows
. Adddelivery_mode='foreground'
when a background-delivered click does not land.There is no wait tool. The loop waits by callingget_desktop_state
again, so say that in the system prompt or the model will invent something worse.
Point it at the exposed port and give it the task.
Because the MCP tools are presented as ordinary function tools, this works against endpoints that reject the provider-native computer-use tool types. That is not hypothetical: on the gateway used here, the same model with the same image in the same second returned 200 for an ordinary function tool and 403 for Anthropic's computer_20250124
, and computer_use_preview
was refused outright.
The complete()
wrapper above exists only for that gateway — it is streaming-only, and it rejects role: system
. Against an endpoint without those quirks, call litellm.acompletion
directly.
A full run — launcher to standing in a new world — took 52 steps locally and 51 on Fleet, roughly twenty minutes, most of it waiting on the software renderer. Expect the model to spend long stretches doing nothing but re-screenshotting.
Give the model help with coordinates. A vision model without grounding guesses pixel positions and misses: in one run an ungrounded model clicked at (1226, 210) four times, nowhere near the button it wanted, then declared it had no desktop tool. cua-driver's list_windows
and pid-scoped clicks avoid most of this, and a grounding pass over the screenshot removes the rest.
Publish the installed sandbox as a containerDisk# #
Everything above is a one-time cost, and none of it has to be repeated — least of all on Fleet, where a manual GUI install is the least pleasant part of this guide. A cua sandbox boots from a containerDisk: an OCI image whose entire content is one file at /disk/disk.img
. Push the disk you just built as one, and every later sandbox, local or Fleet, starts with Prism, Java, Mesa and the game files already in place.
Despite the name, /disk/disk.img
is a qcow2, not a raw image. The puller looks for exactly disk/disk.img
or ./disk/disk.img
inside the layer tarball and caches whatever it finds under ~/.cua/cua-sandbox/images/container-disks/
. Nothing reads the extension — it is a KubeVirt convention.
Sandbox.snapshot()
is a different feature and not a substitute: it forks a cloud sandbox in place, raises NotImplementedError: Snapshots are only supported for cloud sandboxes
on the local runtime, and returns an Image
you cannot push or pull.
Build the image before you sign in, never after. A disk that has ever held a signed-in Minecraft account cannot be reliably cleaned, and a containerDisk you publish is a disk anyone can pull.
Deleting Prism's accounts.json
is not enough, and neither is deleting it and then zero-filling the volume's free space. Both were done to a disk where the game had been played, and the Microsoft profile name, the profile UUID and a full Mojang access-token JWT were still recoverable from the exported image. Mapping the byte offsets back to files with ntfscluster
put them in three places:
— most of them. The JVM heap, swapped out, holding thepagefile.sys
--accessToken
command line and raw HTTPS response bodies fromapi.minecraftservices.com
. Free-space zeroing cannot reach it, because the pagefile is an allocated file.File slack inside a live log. Clusters allocated toinstances/1.20.1/minecraft/logs/latest.log
past its valid-data length still held`Setting user: <name>`
from a longer earlier run. This is also why searching from inside the guest proves nothing:`findstr`
stops at end-of-file, the disk image does not.Unallocated clusters the zero-fill missed, because NTFS does not reuse every freed cluster when you write one large file.
No scrub turns "my search found nothing" into "no credential is present". Build the image without ever signing in and the question does not arise — and signing in is the reader's step anyway, since every reader needs their own Microsoft account.
Build the image without an account#
Follow the walkthrough above but skip the sign-in section entirely. Prism's Quick Setup ends on an Add Microsoft account page that also has a Finish button; click Finish.
Two steps that normally happen as a side effect of signing in and launching then have to be done explicitly:
Create the instance.* Add Instance → Custom*, search1.20.1
,OK. Prism downloads the client jar, libraries and assets with no account attached.** Fetch Java without launching.The walkthrough gets Prism's Java runtime by clicking Launch, which needs an account. UseSettings → Java → Installations →instead and pick a MojangDownload****Java 17** runtime —java-runtime-gamma
17.0.15
for 1.20.1. It lands inC:\mc\prismw\java\java-runtime-gamma\bin\
, which is where the Mesa script then copiesopengl32.dll
. Run that scriptafterthis, not before.
Then close the launcher and make two edits. Prism rewrites its config on exit, so doing this while it is running achieves nothing.
Prism refuses to add an offline account until a Microsoft account that owns Minecraft has been added at least once — "You must add a Microsoft account that owns Minecraft before you can add an offline account." So there is no way to smoke-test the game on the finished image without signing into it, which is exactly what you are avoiding. Test the game on the sandbox you built it from, before the export.
Shut the guest down from inside#
Do not stop the sandbox with sb.stop(). The QEMU runtime treats the session disk as ephemeral —
`runtime.start()`
reads `opts.pop("ephemeral", True)`
and `Sandbox.create()`
never passes the flag — so `stop()`
unlinks ~/.cua/cua-sandbox/images/sessions/<name>.qcow2
, which is the disk you just spent an hour building. Starting the same sandbox name again is no safer: create_session_disk()
unlinks and recreates the overlay every time.Shut Windows down from inside instead, and wait for the QEMU process to exit before touching the file.
Export the disk#
The session disk is a qcow2 overlay on the base containerDisk. qemu-img convert
flattens the chain and -c
compresses the result, so one command produces a standalone image.
Expect it to be slow and CPU-bound rather than I/O-bound — -c
is single-threaded zlib. For the image built here it took 8 min 44 s and produced 7,697,072,128 bytes (7.14 GiB) from a 3.40 GB overlay on the 5.62 GiB base disk, 64 GiB virtual. qemu-img
itself needs almost nothing resident — under 20 MB — so the size of the host does not matter.
Zero-filling the volume's free space from inside Windows before shutting down makes the export smaller, but only if QEMU is told to discard the zeroes instead of storing them. Attach the disk with discard=unmap,detect-zeroes=unmap
and the writes are dropped, so the source qcow2 shrinks rather than growing toward its 64 GiB virtual size.
Inside the guest, write zeroes to a file until the volume is nearly full and then delete it. Leave about a gigabyte of headroom; filling C:
completely destabilises Windows. Zeroing roughly 46 GB took under two minutes on the disks here, because QEMU drops the writes rather than committing them.
Build the OCI image and push it#
The Dockerfile is two lines, and FROM scratch
is not an optimisation — a containerDisk must contain nothing else.
That took 6 min 28 s here — 3 min 48 s exporting the layer and 1 min 57 s pushing it. The layer came out at 7,631,366,006 bytes as application/vnd.oci.image.layer.v1.tar+gzip
: gzip buys essentially nothing on a qcow2 that is already zlib-compressed, so budget for pushing the full size rather than expecting the progress bar to outrun it.
--provenance=false --sbom=false
suppresses buildx's attestation manifests. With them off, buildx publishes a plain application/vnd.oci.image.manifest.v1+json
and no image index at all, which is the simplest thing for a single-platform disk to be. cua's puller does follow an index and skips attestation children — it filters on os == "linux"
and on the vnd.docker.reference.type
annotation — so an index is not fatal, but there is no reason to publish one here.
A GHCR package is private when first pushed, and Fleet pulls anonymously. Fleet's nodes have no credentials for your registry, so a private package fails there no matter how well docker login
works on your own machine. Make the package public before testing on Fleet — Package settings → Change visibility → Public — and only publish an image you are willing to hand to strangers, which is what the sign-in warning above is about.
A gh auth login
token does not carry write:packages
. docker login ghcr.io
still succeeds with it, and the push then fails at the very end with denied: permission_denied: The token provided does not match expected scopes
. Run gh auth refresh -h github.com -s write:packages
first, or use a PAT that has the scope.
Boot the published image#
os_type
is what selects firmware on both paths: the local runtime only looks for OVMF when it is "windows"
, and the Fleet transport only sets Firmware.EFI
for it. A Windows containerDisk that claims to be Linux boots SeaBIOS against a GPT/ESP disk and never reaches the readiness probe, so say which one it is:
IMAGE
is then a drop-in replacement for `Image.windows().expose(3000)`
in both snippets earlier in this guide — the local `Sandbox.create(..., local=True, runtime=QEMURuntime(...))`
call and the Fleet one. Nothing else changes: the same EXTRA_ARGS
locally, the same agent loop, and on Fleet the same GALLIUM_DRIVER=softpipe
.
sb.tunnel.forward(3000)
is not available on every Fleet path. A sandbox handed back by a pool claim carries the base FleetTransport
, which does not implement port forwarding, and the error names the transport rather than the cause: FleetTransport does not support port forwarding
. A sandbox created directly carries FleetCloudTransport
, which does. If you hit it, reach the service through Fleet's proxy at /api/svc/<namespace>/<sandbox>-port-3000/
instead.
Booted locally, that image printed Image(windows/registry:latest, kind=vm, ...)
, came up on the first try, and had everything in it: instances\1.20.1
, java\java-runtime-gamma
, Mesa's opengl32.dll
beside javaw.exe
, minecraft-1.20.1-client.jar
, MaxMemAlloc=2048
— and Test-Path C:\mc\prismw\accounts.json
returning False
. Opening Prism shows the Quick Setup account page and No accounts added!, which is what a correctly-built image looks like.
Use a registry that speaks HTTPS. The puller goes through oras
, which never tries plain HTTP, so a scratch docker run registry:2
on localhost:5000
fails with SSLError(1, '[SSL: WRONG_VERSION_NUMBER] wrong version number')
before it ever fetches a manifest. Give the registry a certificate and point REQUESTS_CA_BUNDLE
at the CA if you want to rehearse this locally.
Expect the first Fleet boot on a given node to be slow: it has to pull the whole image before the sandbox can start, and Fleet enforces a 300-second bind deadline that time_to_start=
does not extend, so a cold pull can surface as BindDeadlineExceeded: no adoptable Sandbox within 300s
.
A second failure to expect is 403 k8s request is not allowed
on update template
. A template can be created but never updated: both branches of the gateway's image policy are guarded by input.method != "PATCH"
, so any request that takes the update path is refused, with the same opaque message you get for a disallowed image. Reusing the sandbox name guarantees it. A fresh name usually avoids it but not reliably — of four boots of the same image, one reused name and one fresh name both returned 403, while two other fresh names reached READY
in 157 s and 187 s. Retry; it is intermittent, and nothing about your image changes the outcome.
The SDK surfaces these 403s as PoolAccessDeniedError
. The same error also appears when the pool name you chose is already owned by another account — pool names are globally unique across accounts — and in that case the fix is a different pool name, not a retry.
The reader's remaining work is the part that has to be theirs: open Prism, Accounts → Add Microsoft, approve the device code, and click Launch.
Run the same thing on Fleet# #
The image and the agent loop are identical on Fleet. Two things change: there is no local=True
and no runtime=
, and the MCP endpoint is reached through Fleet's service proxy rather than a forwarded localhost port.
.expose(3000)
becomes a Fleet service named port-3000
, and sb.tunnel.forward()
hands you its URL — the same call documented in Forward a port from a sandbox, so there is nothing Fleet-specific to hand-assemble.
That is the same run()
as above, with only the URL and an auth header changed. A Fleet Windows sandbox takes about three minutes to become ready, against about thirty seconds for a warm local one, and GET healthz
on that service URL answers ok
when cua-driver is up.
Notice there is no -cpu host
here. That flag exists on the local path because the bare-metal runtime defaults to the thin qemu64
model; a Fleet sandbox is provisioned for you and already reports a full host CPU — Intel Xeon Processor (SapphireRapids)
, with AVX, AVX2 and AVX-512 all present — so there is nothing to override, and no QEMU arguments to pass.
Pool.apply
also accepts cpu
and memory_mb
, but sizing a Fleet sandbox is account-dependent: passing them routes the request through a gated custom-resource path, which returned 403 create pool: k8s request is not allowed
at every size until a card-on-file requirement was lifted for the account. The default sandbox — 4 vCPU and 4 GB — is what this guide was written against, and it is enough.
On Fleet the game needs one extra environment variable: GALLIUM_DRIVER=softpipe. With Mesa's default llvmpipe renderer, Minecraft dies during resource every time —
Process crashed with exitcode -2147024809
, no Java exception, no hs_err
file, nothing in the Windows event log, the log simply stopping after Re ResourceManager
. Switching Mesa to its softpipe
rasteriser fixes it, and the game runs.Set the variable in the process that launches the launcher, so the game inherits it — a machine-level variable does not reach an already-running process, and a test that silently did not apply looks exactly like a test that failed. setup.ps1
above already started Prism without it, so close the running launcher first and start it again like this.
Softpipe is a reference rasteriser with no JIT, so it is considerably slower than llvmpipe — allow several minutes for the title screen and longer again for world generation.
Use client credentials, not a cua auth login
session token. The session token is short-lived and is held without refresh, so a long provisioning wait dies partway with 401 auth token is invalid
. Client-credential tokens expire too — the ones issued here came back with expires_in
of 900 seconds — so a run longer than that has to re-mint the token and rebuild the MCP client.
What that crash is not, since each obvious explanation was tested and eliminated: not the Minecraft version or the Java/LWJGL generation (1.20.1 on Java 17 with LWJGL 3 and 1.12.2 on Java 8 with LWJGL 2 fail identically), not the heap (forcing Prism's auto-sized -Xmx2717m
down to -Xmx1024m
changed nothing), and not the size of the machine (the same local session disk rebooted with -m 4096 -smp 4
, matching Fleet exactly, runs the game fine). Narrowing llvmpipe's vectors with LP_NATIVE_VECTOR_WIDTH=128
did not help either, which argues the fault is not simply wide-vector code generation.
Troubleshooting# #
| Symptom | Cause | Fix |
|---|---|---|
QEMU refuses to start with -cpu host |
no KVM or HVF — for example an x86_64 guest on Apple Silicon, which runs under TCG | use a host with hardware virtualisation, or the Fleet path |
| Launcher never appears, no error | MSVC build without the VC++ redistributable | use the MinGW portable build |
| Guest has an IP address but cannot resolve names | both user-mode NICs offered the same address | give the second NIC its own subnet |
GLFW error 65542: WGL: The driver does not appear to support OpenGL |
Mesa DLLs missing beside the javaw.exe actually in use, or the MSVC Mesa build failed to load |
copy the MinGW Mesa DLLs into every javaw.exe directory |
| Game exits during resource with no Java exception, local | default qemu64 CPU model |
append -cpu host to extra_args |
Game exits during resource with exitcode -2147024809 , Fleet |
Mesa's default llvmpipe renderer | set GALLIUM_DRIVER=softpipe in the process that starts the launcher, and restart the launcher if it is already running |
Permission denied: user policy: tool 'X' is not allowed |
cua-driver's YAML policy refuses that tool, which list_tools() advertises anyway on every driver released so far |
use an allowed tool — get_desktop_state instead of get_screen_size , list_windows instead of get_accessibility_tree |
| Model replies with empty output on the first call | endpoint is streaming-only | issue stream=True and rebuild with litellm.stream_chunk_builder |
Sandbox from Image.from_registry() never becomes ready |
os_type defaults to "linux" , so a Windows disk gets BIOS instead of UEFI |
pass os_type="windows", kind="vm" (needs cua-sandbox 0.3.3; before that, dataclasses.replace() on the result) |
SSLError(1, '[SSL: WRONG_VERSION_NUMBER] wrong version number') while pulling |
the registry speaks plain HTTP; oras only speaks HTTPS |
give the registry a certificate, and set REQUESTS_CA_BUNDLE for a self-signed one |
denied: permission_denied: The token provided does not match expected scopes at the end of a push |
the gh OAuth token carries no write:packages |
gh auth refresh -h github.com -s write:packages , or use a PAT that has it |
| Fleet cannot pull the image you just published | GHCR packages are private on first push, and Fleet pulls anonymously | make the package public |
| The session disk vanished after a run | stop() unlinks the ephemeral session overlay, and starting the same name recreates it |
shut the guest down from inside, and copy the qcow2 before anything else touches it |