Chạy Minecraft trong Windows Sandbox cho Computer Use Agents

Khám phá cách khởi động Windows Sandbox, cài Minecraft Java Edition và điều khiển trò chơi thông qua agent AI sử dụng MCP server. Hướng dẫn toàn diện này bao gồm từ thiết lập mạng, cài driver OpenGL cho đến xuất bản sandbox thành containerDisk có thể tái sử dụng.

Minecraft là ứng dụng hoàn hảo để kiểm tra giới hạn của Windows Sandbox: nó đòi hỏi truy cập internet, Java runtime, OpenGL hoạt động và giao diện đồ họa có thể điều khiển bằng thao tác click. Hướng dẫn này sẽ boot một sandbox Windows, cài Minecraft Java Edition và giao nó cho agent thông qua MCP server của cua-driver — cùng một quy trình hoạt động cả trên sandbox local lẫn trên Fleet.

Yêu cầu trước khi bắt đầu

• cua-sandbox 0.3.3 hoặc mới hơn
• Máy chủ có ảo hóa phần cứng cho đường dẫn local (Linux x86_64 với /dev/kvm, hoặc Intel Mac)
• Tài khoản Microsoft sở hữu Minecraft Java Edition
• LLM endpoint hỗ trợ vision cho vòng điều khiển agent

Lưu ý quan trọng: Tham số -cpu host chỉ hoạt động với KVM hoặc HVF. Trên Apple Silicon với TCG emulation, tham số này sẽ bị từ chối hoàn toàn.

Khởi động Windows Sandbox

Quá trình thiết lập bao gồm ba phần bổ sung trên nền tảng tiêu chuẩn:

1. Expose port 3000 để publish MCP server của cua-driver
2. Thêm network interface thứ hai — interface mặc định bị cô lập với restrict=on, ngăn truy cập internet mà Minecraft cần
3. Sử dụng -cpu host — model qemu64 mặc định quá yếu cho software OpenGL driver

import asyncio
from cua import Image, QEMURuntime, Sandbox

EXTRA_ARGS = [
    '-netdev', 'user,id=net1,net=10.0.3.0/24,host=10.0.3.2,dns=10.0.3.3',
    '-device', 'virtio-net-pci,netdev=net1,mac=52:55:00:d1:55:02',
    '-cpu', 'host',
]

async def main():
    sb = await Sandbox.create(
        Image.windows().expose(3000),
        name='mc-win',
        local=True,
        runtime=QEMURuntime(
            mode='bare-metal',
            cpu_count=12,
            memory_mb=16384,
            extra_args=EXTRA_ARGS,
        ),
    )
    mcp_port = sb.exposed_ports[3000]
    print(f'cua-driver MCP on http://127.0.0.1:{mcp_port}/mcp')
    await sb.disconnect()

asyncio.run(main())

Một boot nóng mất khoảng 30 giây. Kiểm tra GET /healthz trên port đã expose để xác nhận cua-driver đã sẵn sàng.

Cấu hình mạng quan trọng

• Network interface thứ hai cần subnet riêng — nếu dùng subnet mặc định 10.0.2.0/24, Windows sẽ drop một interface xuống link-local 169.254.x.x
• Đọc port từ sb.exposed_ports, không dùng sb.tunnel.forward() trên local transport (sẽ raise NotImplementedError)

Cài launcher và software OpenGL driver

Sandbox GPU là Microsoft Basic Display Adapter chỉ hỗ trợ OpenGL 1.1, trong khi Minecraft 1.17+ cần OpenGL 3.2. Giải pháp: dùng Mesa3D's opengl32.dll (llvmpipe) — triển khai OpenGL hoàn toàn bằng phần mềm.

Chọn bản MinGW builds: Bản MSVC của Prism Launcher và Mesa phụ thuộc Visual C++ redistributable mà Windows Server 2022 không có sẵn.

$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'

New-Item -ItemType Directory -Force -Path C:\mc | Out-Null

# Prism Launcher — đăng nhập Microsoft device authorization không cần browser
Invoke-WebRequest -UseBasicParsing -OutFile C:\mc\prism.zip `
'https://github.com/PrismLauncher/PrismLauncher/releases/download/11.0.3/PrismLauncher-Windows-MinGW-w64-Portable-11.0.3.zip'
Expand-Archive C:\mc\prism.zip -DestinationPath C:\mc\prismw -Force

# 7-Zip cho định dạng .7z của Mesa
Invoke-WebRequest -UseBasicParsing -OutFile C:\mc\7z.msi 'https://www.7-zip.org/a/7z2408-x64.msi'
Start-Process msiexec.exe -ArgumentList '/i','C:\mc\7z.msi','/qn' -Wait

# Mesa3D software OpenGL
Invoke-WebRequest -UseBasicParsing -OutFile C:\mc\mesa.7z `
'https://github.com/pal1000/mesa-dist-win/releases/download/26.1.6/mesa3d-26.1.6-release-mingw.7z'
& 'C:\Program Files\7-Zip\7z.exe' x C:\mc\mesa.7z -oC:\mc\mesamw -y | Out-Null

Start-Process -FilePath C:\mc\prismw\prismlauncher.exe -WorkingDirectory C:\mc\prismw

Đăng nhập và tạo instance

Prism mở Quick Setup wizard khi chạy lần đầu. Điều hướng qua wizard đến Accounts → Add Microsoft. Prism hiển thị QR code và mã device code 8 ký tự.

Đọc mã từ screenshot, mở https://www.microsoft.com/link trong browser của bạn, nhập mã và xác nhận đăng nhập.

Copy Mesa DLLs vào thư mục Java

Sau khi click Launch lần đầu, game sẽ fail với lỗi GLFW error 65542 — điều này là bình thường vì Mesa chưa được cài đúng chỗ. Windows ưu tiên load opengl32.dll từ thư mục của executable đang chạy:

$dirs = Get-ChildItem C:\mc -Recurse -Filter javaw.exe -ErrorAction SilentlyContinue |
Select-Object -ExpandProperty DirectoryName -Unique

foreach ($d in $dirs) {
    Copy-Item C:\mc\mesamw\x64\opengl32.dll, C:\mc\mesamw\x64\libgallium_wgl.dll $d -Force
    Write-Output "mesa -> $d"
}

Điều khiển bằng agent qua MCP

Agent chạy như một vòng lặp nhỏ: liệt kê MCP tools, giao chúng cho model như function tools thông thường, gọi tool được chọn và xử lý kết quả.

Ba điểm quan trọng về cua-driver tools:

1. YAML policy kiểm soát tool có thể chạy — list_tools() không phản ánh policy này. Một số tool sẽ bị từ chối khi gọi thực sự với lỗi "Permission denied: user policy"
2. Clicks được gửi đến một ứng dụng cụ thể, không phải toàn màn hình — dùng click(pid=..., x=..., y=...) với pid tìm được từ list_windows
3. Không có tool wait — vòng lặp chờ bằng cách gọi get_desktop_state lặp lại

TASK = """
Prism Launcher is open, with a Minecraft instance and a signed-in account.
Select the instance and click Launch. Minecraft uses a software renderer, so the
window takes minutes to appear and repaints slowly — keep calling
get_desktop_state to watch it, and do not restart anything. On the title screen
click Singleplayer, then Create New World, then Create New World again. Stop as
soon as you are inside the world (terrain in first person, hotbar and hearts
visible) and reply DONE. Never press Escape while Minecraft is in the foreground.
"""

Một run hoàn chỉnh từ launcher đến khi đứng trong world mới mất 52 bước local và 51 trên Fleet, khoảng 20 phút — phần lớn thời gian chờ software renderer.

Mẹo quan trọng: Vision model không có grounding sẽ đoán sai vị trí pixel. Trong một lần chạy, model đã click vào (1226, 210) bốn lần mà không trúng nút, rồi tuyên bố không có desktop tool. Hãy dùng list_windows và pid-scoped clicks cùng với grounding pass trên screenshot.

Xuất bản sandbox thành containerDisk

Điểm mạnh của cách tiếp cận này: mọi thiết lập là chi phí một lần. Bạn có thể publish toàn bộ sandbox dưới dạng containerDisk — một OCI image chứa toàn bộ disk image — để không bao giờ phải lặp lại quá trình cài đặt thủ công.

Cảnh báo bảo mật cực kỳ quan trọng

Xây dựng image TRƯỚC khi đăng nhập, không bao giờ sau đó. Một disk từng chứa tài khoản Minecraft đã đăng nhập không thể được làm sạch đáng tin cậy:

• pagefile.sys — chứa JVM heap, access token, và raw HTTPS response bodies
• File slack trong log files — dữ liệu cũ vẫn còn trong cluster đã allocated
• Unallocated clusters — NTFS không tái sử dụng mọi freed cluster khi ghi file lớn

Việc xóa accounts.json và zero-fill free space không đủ — Microsoft profile name, profile UUID và toàn bộ Mojang access-token JWT vẫn có thể khôi phục từ exported image.

Quy trình build image không cần tài khoản

1. Theo walkthrough nhưng bỏ qua phần đăng nhập — click Finish ở trang Add Microsoft account
2. Tạo instance: Add Instance → Custom → search 1.20.1
3. Tải Java: Settings → Java → Installations → Download → chọn java-runtime-gamma 17.0.15
4. Chỉnh MaxMemAlloc=2048 trong prismlauncher.cfg
5. Xóa installers không cần thiết
6. Shutdown từ bên trong guest — không dùng sb.stop() vì sẽ xóa session disk

Export và publish

# Flat chain và nén
qemu-img convert -O qcow2 -c ~/.cua/cua-sandbox/images/sessions/mc-win.qcow2 disk.img

# Tạo OCI image
FROM scratch
ADD disk.img /disk/disk.img

# Build và push
docker buildx build --provenance=false --sbom=false \
  -t ghcr.io/[username]/minecraft-workspace:1.20.1 --push .

GHCR packages là private mặc định khi push lần đầu, và Fleet pull anonymously. Phải public package trước khi test trên Fleet. Chỉ publish image bạn sẵn sàng trao cho người lạ — disk này ai cũng pull được.

Chạy trên Fleet

Quy trình trên Fleet gần như giống hệt, chỉ khác ở ba điểm:

1. Không có local=True và runtime=
2. MCP endpoint truy cập qua Fleet service proxy thay vì localhost forwarded port
3. Thêm biến môi trường GALLIUM_DRIVER=softpipe — Mesa's llvmpipe mặc định crash Minecraft trên Fleet

import httpx
from cua import Image, Pool, Sandbox

pool = await Pool.apply(Image.windows().expose(3000), name='mc-fleet')
sb = await Sandbox.create(pool=pool, name='mc-fleet', time_to_start=900)
tunnel = await sb.tunnel.forward(3000)

token = httpx.post(
    'https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token',
    data={'grant_type': 'client_credentials',
          'client_id': os.environ['CUA_CLIENT_ID'],
          'client_secret': os.environ['CUA_CLIENT_SECRET']},
).json()['access_token']

await run(tunnel.url + 'mcp', TASK, 'your-model',
          headers={'Authorization': f'Bearer {token}'})

Tại sao GALLIUM_DRIVER=softpipe?

Với llvmpipe mặc định, Minecraft crash trong quá trình load resources với exitcode -2147024809 — không có Java exception, không có hs_err file, log dừng đột ngột sau "Reloading ResourceManager". Switching sang softpipe rasteriser giải quyết vấn đề.

Softpipe là reference rasteriser không có JIT nên chậm hơn đáng kể — cho phép vài phút cho title screen và lâu hơn cho world generation.

Bảng xử lý sự cố

Triệu chứng	Nguyên nhân	Khắc phục
QEMU từ chối -cpu host	Không có KVM/HVF — ví dụ guest x86_64 trên Apple Silicon	Dùng host có hardware virtualisation hoặc đường dẫn Fleet
Launcher không xuất hiện, không lỗi	Bản MSVC thiếu VC++ redistributable	Dùng bản MinGW portable
Guest có IP nhưng không resolve được tên miền	Cả hai NIC user-mode dùng cùng địa chỉ	Cho NIC thứ hai subnet riêng
GLFW error 65542	Thiếu Mesa DLL cạnh javaw.exe đang dùng	Copy MinGW Mesa DLLs vào mọi thư mục javaw.exe
Game exit trong lúc load resources, local	Model CPU qemu64 mặc định	Thêm -cpu host vào extra_args
Game exit với -2147024809, Fleet	llvmpipe mặc định của Mesa	Set GALLIUM_DRIVER=softpipe và khởi động lại launcher
Permission denied: user policy	YAML policy từ chối tool mà list_tools() vẫn hiển thị	Dùng tool được phép — get_desktop_state thay get_screen_size
Model trả output rỗng	Endpoint chỉ hỗ trợ streaming	Dùng stream=True và rebuild với litellm.stream_chunk_builder
Sandbox không bao giờ ready	os_type mặc định là "linux"	Truyền os_type="windows", kind="vm"
Fleet không pull được image	GHCR private sau push đầu tiên	Public package
Session disk biến mất sau khi chạy	stop() xóa ephemeral session overlay	Shutdown guest từ bên trong và copy qcow2 trước

Kết luận

Phương pháp này biến một tác vụ tưởng chừng phức tạp — điều khiển Minecraft bằng AI agent — thành quy trình có thể tái sản xuất hoàn toàn. Từ việc xử lý các thách thức về OpenGL software rendering, cấu hình mạng phức tạp, đến xuất bản containerDisk tái sử dụng, hướng dẫn này cung cấp nền tảng vững chắc cho việc phát triển computer use agents trong môi trường Windows sandbox.

Với Vietnamese developers, đây là cơ hội để khám phá khả năng của AI agents trong việc điều khiển GUI applications — một hướng đi đầy tiềm năng cho automation và testing trong các dự án phần mềm.