Allows managing QEMU virtual machines for sandboxed OS inspection and testing: booting ISOs, taking screenshots, creating/restoring snapshots, executing commands in the VM, and transferring files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@uos-mcp fingerprint this Windows 7 ISO and boot it in a sandbox VM"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skills, tools, an MCP server and a shared knowledge base that let an AI coding agent reverse engineer an existing operating system from its ISO and rebuild it — ReactOS style — component by component, until apps written for the original OS run on the rebuild.
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, or anything that
reads AGENTS.md or speaks MCP. Point the agent at a Windows ISO (any version: XP, 7, 10, 11,
Server), it fingerprints the image, boots it in a headless QEMU sandbox, surveys what the OS
actually exposes, writes behavioral specs, scaffolds ReactOS-style C components, builds them,
boots the rebuild, and tests real Windows apps on it. Every session leaves field notes the next
agent starts from.
ISO ──► fingerprint ──► sandbox VM ──► survey (API surface, traces)
│
behavioral specs ◄──────────────┘
│
scaffold + build (ReactOS-style C, .spec exports)
│
rebuilt image ──► boot in VM ──► test real apps ──► behavior_diff
│
field note for the next agentPick your agent. Each gets the same skills, the universal-os MCP server, and the uos CLI.
Everything below installs straight from this repo — no PyPI release needed yet.
Agent | Install |
Claude Code |
|
Codex / Cursor / VS Code | Clone the repo and start the agent inside it; configs in |
Skills only (any agent) |
|
Anything else |
|
The CLI, anywhere:
uv tool install git+https://github.com/Jenischristan/universal-os # or: pip install git+https://github.com/Jenischristan/universal-osBoth entry points (uos, uos-mcp) land on your PATH. There is no universal-os-mcp
command — the MCP server executable is uos-mcp (uos mcp is the same thing).
You need Python 3.10+, and QEMU for the VM parts (git, cmake, ninja and a MinGW toolchain when you reach the build phase):
sudo apt-get install -y qemu-system-x86 qemu-utils # Debian/Ubuntu
brew install qemu # macOS
winget install SoftwareFreedomConservancy.QEMU # Windowsuos env checks all of it and prints what's missing.
Related MCP server: Windows Sandbox MCP
Rebuild the core of the Windows XP SP3 ISO at
~/isos/en_win_xp_sp3.isofar enough to runnotepad.exeandcmd.exe.
This is a Windows 7 ISO. Fingerprint it, boot it in a VM, dump the kernel32/user32/ntdll API surfaces, and tell me how far the ReactOS component set already covers it.
Take my rebuilt workspace, test Notepad2 on it, and add compat quirks for everything that breaks.
The agent starts with the build-any-os skill and runs the same loop every time:
search the knowledge base; 2. fingerprint the ISO; 3. check the environment;
set up a sandbox lab (VM, snapshots); 5. survey the reference OS (API surfaces, traces);
pick the component route; 7. write behavioral specs; 8. build one working slice;
boot the rebuild and test real apps; 10. write a field note for the next agent.
knowledge/ holds field notes: how specific OS rebuilds actually went — the exact ISO
versions, the component order that worked, the interface facts, the verification, the gotchas
(symptom → cause → fix). Every agent that finishes a milestone can open a PR with its note, so
the next agent starts where the last one left off.
uos kb search "windows xp ntdll" # before you start: prior art
uos kb new --os "windows-xp" --component ntoskrnl --title "First boot" --agent "Claude"
uos kb check knowledge/os/windows-xp/....mdContribution rules, for humans and AIs, are in RULES.md: no Microsoft binaries, no decompiled
code, no media links, honest status and verification.
Part | What it does |
MCP server ( | 39 tools over stdio: ISO inspect/fingerprint, VM lifecycle (boot, screenshot, snapshot, exec, file transfer), PE analysis, API-surface dumps, syscall-trace plans, behavior diffs, component scaffolds, compat shims, reference-repo cloning, app-compat testing, knowledge base |
| The same tools from a shell — for agents without MCP and for humans |
skills/build-any-os | The whole loop, hard rules, and playbooks per phase (fingerprint, boot, survey, route, spec, build, verify, publish) |
knowledge/ | Field notes from previous rebuilds + a generated INDEX |
prompts/ | Ready-made phase prompts for any MCP client |
examples/ | A worked example: workspace layout, first build, first app test |
CI | GitHub Action running the tests, CLI smoke checks and knowledge-base lint on every push |
RULES.md)Everything untrusted runs inside the sandbox VM, never on the host. The reference ISO is never mounted on the host; it is read with the built-in ISO parser or booted in QEMU.
Inspection is free; shipping is not. Inside the VM the agent may run, trace, dump and analyze anything. What may enter the rebuilt OS repo is: interface facts (names, ordinals, versions, structures), behavioral specs, and clean-room code. What may not: Microsoft binaries, drivers, fonts, registry hives, decompiled output, links to OS media.
VM networking is OFF by default; enabling it needs the user's explicit OK.
Snapshot before risky operations; restore to undo.
Keep a journal: WORKSPACE.md in the workspace. It becomes the field note at the end.
No activation/DRM/licensing bypass, no pirate media, ever.
MIT. universal-os is tooling for interoperability and education — the same legal footing as
ReactOS and Wine. It ships no Microsoft code, no Microsoft binaries, and does not distribute
OS media. What you build with it must pass the same rules; uos kb check and CI enforce the
basics, and your jurisdiction and lawyer own the rest.
Analyze one PE binary (headers, sections, imports, exports, version resource).
Works on a file extracted INSIDE the VM sandbox or copied out with vm_get_file. Reports interface facts only — no disassembly, nothing shippable from the binary.
Inputs: path (required). Returns: result
Diff two API-surface dumps (reference vs rebuilt build): per-module export coverage, missing/extra exports. THE key progress metric for compatibility.
Inputs: current (required), baseline (required), out, workspace. Returns: result
Return the concrete build plan for the workspace and check which host toolchains are present (cmake/ninja/mingw/RosBE). The AI runs the steps in src/.
Inputs: workspace (required), toolchain. Returns: result
Find (and with confirm=true delete) regenerable junk in the workspace: pycache, .pytest_cache, build/, dist/, .pyc/.pyo/*.tmp. Dry run by default - the response lists what would go. Sources, WORKSPACE.md, reports/ and third-party/ are never touched; VMs live under UOS_HOME and are unaffected. Use before archiving or sharing the workspace.
Inputs: workspace (required), confirm. Returns: result
Clone a reference implementation into third-party/ (read-only reference): reactos, wine, qemu, virtio-win, or any git URL. Clone repos as needed when a component needs proven patterns or test suites.
Inputs: workspace (required), dest, repo. Returns: result
Aggregate all recorded app tests into a dated compatibility report (pass rate, failing labels, next-step guidance).
Inputs: workspace (required). Returns: result
Dump the interface surface of a directory of reference DLLs: export names, ordinals, imports, versions -> JSON + MD. This is the rebuild's target contract.
IMPORTANT (moderate guardrails): keep the inspected copies OUTSIDE the repo (e.g. ~/inspect/); only the generated surface JSON/MD goes into workspace/api/.
Inputs: out (required), src_dir (required), pattern, workspace, +1 more. Returns: result
Check the host environment: qemu, qemu-img, git, cmake, ninja, mingw, /dev/kvm. Run once at session start; the result decides what the AI can do right now.
Inputs: no named parameters. Returns: result
Identify the Windows version/build inside an install ISO (any version): layout markers, version resources of setup binaries, cversion.ini — with confidence.
Run this first. It decides the API-surface strategy (NT 5.x vs 6.x differ a lot). Version facts are interface facts — fine to journal; media contents stay out of the repo.
Inputs: iso_path (required). Returns: result
Generate .spec + stub .c for one DLL straight from an API-surface dump (stubs return E_NOTIMPL; implement from behavioral specs, highest-import first).
Inputs: module (required), workspace (required), surface_json (required), max_stubs. Returns: result
Scaffold a small compat shim for one module: records per-quirk workarounds that unblock specific apps (quirks: semicolon-separated; for_apps: comma-separated).
Inputs: module (required), workspace (required), quirks, for_apps. Returns: result
Create a rebuild workspace: src/{boot,drivers,subsystems,dll,shell,include,apps}, spec/, api/, tests/, reports/, third-party/, plus WORKSPACE.md journal.
Everything the AI builds lands here. target examples: windows-xp, windows-7, windows-any (version decided after fingerprint_windows).
Inputs: path (required), iso, name, target, +1 more. Returns: result
Extract ONE file from an install ISO to the host inspect dir — no mounting (pure ISO9660/Joliet read), e.g. member='/I386/NTOSKRNL.EX_' dest='~/inspect/xp/'.
Inspection only: keep extracted copies OUTSIDE the rebuilt-OS repo and keep only interface facts (RULES.md). Pair with analyze_pe / dump_api_surface.
Inputs: dest (required), member (required), iso_path (required), max_mb. Returns: result
List an install ISO's contents WITHOUT mounting it (pure ISO9660/Joliet read).
Use this before any VM work: confirms the image is readable, shows the layout (I386/ legacy vs SOURCES/ modern), and surfaces version markers. Run fingerprint_windows for the full version verdict.
Inputs: iso_path (required), max_entries. Returns: result
Validate an install ISO before use. Checks that the media exists and contains a recognizable Windows boot/install structure with no host-side mounting.
Inputs: iso_path (required). Returns: result
Lint a field note: required sections + prohibited-content scan (no binary dumps, no media links). Run before opening a PR.
Inputs: note (required). Returns: result
Regenerate knowledge/INDEX.md from all notes' front matter.
Inputs: no named parameters. Returns: result
Create a field-note template for this rebuild. Fill it while working, then kb_check before sharing. One note per os+component milestone.
Inputs: title (required), os_name (required), component (required), tags, +2 more. Returns: result
Report which knowledge-base roots resolve and where new notes go (repo checkout / packaged seed / UOS_HOME). Use when kb_search comes back empty and you need to know why.
Inputs: no named parameters. Returns: result
Search field notes from previous rebuild attempts (routes, gotchas, versions). Search BEFORE starting — prior art saves the whole session. Covers the repo knowledge base, the wheel's seed notes, and $UOS_HOME/knowledge.
Inputs: query (required), limit. Returns: result
Append a dated entry to tests/REGRESSIONS.md (status: pass|regressed|fixed|wip).
Inputs: note (required), status (required), workspace (required). Returns: result
Scaffold a ReactOS-style component: CMakeLists.txt, .spec export table, .c with DllMain, README, and an API test file.
exports: comma-separated export names from the API surface. Implementation always comes from behavioral specs written in spec/ — never from decompiled bodies.
Inputs: name (required), workspace (required), kind, exports, +1 more. Returns: result
Full app-compat cycle on the rebuilt (or reference) OS: copy the app in, run install_cmd then the app, capture exit/output, screenshot, record PASS/FAIL.
install_cmd/run_cmd: single command lines (argv[0] + args). Results go to tests/results/ and tests/RESULTS.md in the workspace. Use reference apps the user owns (RULES.md).
Inputs: vm (required), args, label, run_cmd, +4 more. Returns: result
Write a concrete NT-syscall/API tracing plan for this VM (ETW/WPR steps, KDNET setup, static-surface fallback) and optionally kick off in-guest prep via qemu-ga.
Dynamic tracing needs in-guest tooling; this tool gives the exact commands and can fetch the results with vm_get_file afterwards.
Inputs: vm, workspace, target_app. Returns: result
Boot the VM headless (boot='d' = CD-ROM first, 'c' = disk). Waits, then reports status.
Take a screenshot afterwards to see the display. Under pure TCG (no /dev/kvm) a full Windows install can take 30-90+ minutes — snapshot right after setup milestones.
Inputs: name (required), boot, wait_seconds. Returns: result
Create a registered sandbox VM (qcow2 disk + config) for the reference ISO.
Networking is OFF by default — enabling it needs the user's OK (RULES.md). Call vm_boot next. workspace: path of the universal-os workspace this VM belongs to.
Inputs: name (required), iso_path (required), cpus, force, +4 more. Returns: result
Run a command inside the guest via the QEMU guest agent (qemu-ga must be installed).
args: single string, split on whitespace, quotes respected, backslashes kept as-is (Windows guest paths like 'C:\uos-tests\app.exe' survive). Windows guests: use 'cmd.exe' with args like '/c dir C:'. If the agent is missing the error explains how to install it (virtio-win ISO for Windows guests).
Inputs: name (required), path (required), args, timeout. Returns: result
Pull a file out of the guest (e.g. an .etl trace, a crash dump, a test log).
Inputs: name (required), guest_path (required), local_path (required). Returns: result
Tail the VM's serial console log and show the qemu command line (debugging boot).
Inputs: name (required), tail. Returns: result
Swap the CD-ROM medium in the running VM (e.g. insert virtio-win to install the guest agent, then swap back to the reference ISO).
Inputs: name (required), iso_path (required). Returns: result
Set the VM's network flag: OFF by default; enabling needs the user's OK (RULES.md). Only user-mode NAT is implemented (bridge raises honestly). Applies at the next vm_boot - a running VM keeps its old network until shutdown + boot. Check with vm_status.
Inputs: name (required), nat, enable. Returns: result
Copy a file from the host into the guest (via qemu-ga). Guest paths are Windows-style for Windows guests (e.g. C:\uos-tests\app.exe). Size cap: ~2GB practical.
Inputs: name (required), guest_path (required), local_path (required). Returns: result
Restore the running VM to a previously saved snapshot (revert experiments safely).
Inputs: tag (required), name (required). Returns: result
Capture the VM display to a PNG and return its path.
Use it after boot, after each setup screen, and after app tests — it is the AI's eyes on the guest. Read the PNG with vision to decide the next step.
Inputs: name (required). Returns: result
Send a key combo to the VM display: 'ret', 'esc', 'f8', 'ctrl-alt-delete', 'shift-f10', 'spc', 'tab', 'up'/'down'/'left'/'right', single letters/digits.
This drives text-mode installers BEFORE the guest agent exists (the part vm_exec cannot reach). One combo per call; screenshot after each to see the installer's reaction.
Inputs: keys (required), name (required), hold_ms. Returns: result
Shut the VM down (ACPI powerdown; falls back to quit after a timeout; force=true kills immediately). Registry metadata is kept — vm_boot can start it again.
Inputs: name (required), force. Returns: result
Save an internal qcow2 snapshot of the running VM (e.g. 'clean-install', 'pre-app-test').
Snapshot before risky operations: installing apps, changing components, registry edits. Restore with vm_restore. Tag naming: kebab-case, one milestone per tag.
Inputs: tag (required), name (required). Returns: result
Report one VM's status, or every registered VM when name is empty.
Inputs: name. Returns: result
Summarize the rebuild workspace: required dirs (src/spec/api/tests/reports/ third-party), the WORKSPACE.md journal state and its last line, api/ surface count and src/ components. Use to decide the next phase of the loop.
Inputs: workspace (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 39 tools
Most tools have clearly distinct purposes (vm_snapshot vs vm_restore, kb_search vs kb_path, build_plan vs env_check). There is mild overlap in the ISO cluster (iso_inspect/iso_verify/iso_extract/fingerprint_windows) and between env_check/workspace_status/build_plan which all report environment state, but descriptions make the boundaries readable.
Predominantly consistent verb_noun snake_case with clear namespace prefixes (vm_, iso_, kb_). A few deviations exist: fingerprint_windows is noun_verb, and behavior_diff/compat_report/regression_log are noun-only, but all remain readable and predictable.
39 tools is heavy and above the comfortable range, though the domain (VM management, ISO/binary analysis, scaffolding, testing, knowledge base) is genuinely broad and most tools map to a real workflow step. It is on the borderline of over-fragmentation rather than gratuitous sprawl.
Covers the full lifecycle: VM create/boot/snapshot/restore/shutdown, ISO inspection, API-surface analysis and diffing, workspace scaffolding, app-compat testing, and KB management. Minor gaps (e.g. no VM delete/deregister, no in-place file edit) are workable around.
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
The operating system for self-organised AI agent teams.
Deterministic AI agent microtools, no accounts/API keys. fetch_extract: 98% token cut. 47 tools.
