A WinDbg-like Windows debugger for Linux and macOS, with support for kernel-mode and user-mode debugging of virtual and physical machines, and offline crash-dump analysis.
| Debugging via REPL | Debugging via VSCode + DAP |
|---|---|
 |
 |
- WinDbg-style commands and expressions
- Public and private PDB symbols, source lines, and local variables
- Conditional and deferred breakpoints, hardware watchpoints, and breakpoint commands
- KD/KDNET, QEMU GDB, and passive memory backends
- VBS secure kernel (VTL1) and trustlet inspection
- Windows hypervisor (Hyper-V) debugging
- Host-served driver images for driver development
- Python SDK and custom commands
- Editor integration over DAP
- IDA, Binja, Ghidra over the GDB remote protocol
- Agent integration over MCP
ntoseye supports 64-bit AMD64 and ARM64 Windows 10 and 11 targets.
ntoseye supports any target that Windows can debug over KDNET. KVM/QEMU, VMware Workstation, and UTM guests additionally get KDCOM, GDB, and memory-only backends.
ntoseye downloads symbols and images from Microsoft's official symbol server when required. Config, cache, and REPL state live under ~/.ntoseye:
~/.ntoseye/commands/for custom scripted commands~/.ntoseye/symbols/for PDBs and images, a symbol store in thesymstorelayout that WinDbg, IDA, Ghidra, and rizin read~/.ntoseye/aliasesfor command aliases~/.ntoseye/historyfor persistent REPL history~/.ntoseye/sites/for breakpoint instructions a session has planted that the target would not take out itself (user-mode sites, and kernel sites over thegdbbackend), restored by the next attach if that session dies
ntoseye runs on Linux (x86-64, ARM64) and macOS on Apple Silicon. Every method below installs the same debugger; they differ in whether it embeds Python, which custom commands need, and in what they need installed first:
| Method | Custom commands | Needs |
|---|---|---|
| Shell script | no | nothing |
| uv or pipx | yes | Python 3.9 or newer |
| cargo | yes | Rust, and Python 3.9 or newer with its development files (python3-dev on Debian and Ubuntu) |
| pip, for the Python SDK | yes | Python 3.9 or newer |
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dmaivel/ntoseye/releases/latest/download/ntoseye-installer.sh | shInstalls a prebuilt binary to ~/.local/bin.
uv tool install ntoseye # or: pipx install ntoseyeInstalls the ntoseye command in its own environment.
cargo install ntoseyeBuilds the release from crates.io, linked against your Python.
To drive the debugger from your own Python code, install the same package into your project's environment:
pip install ntoseyeThis also puts the ntoseye command in that environment. See the Python SDK documentation.
git clone https://github.com/dmaivel/ntoseye.git
cd ntoseye
cargo build --releaseLike cargo install, a default build embeds Python and needs its development files. To build without it:
cargo build --release --no-default-features --features cli,mcp,dap,gdbserverTo build the documentation site, whose command and SDK references are generated from the source (this runs cargo):
pip install -r docs/requirements.txt
sphinx-build -b dirhtml -n -W docs docs/_build/htmlFor a live preview that rebuilds as you edit, pip install sphinx-autobuild and run sphinx-autobuild -b dirhtml docs docs/_build/html (served at http://127.0.0.1:8000).
If you are using QEMU/KVM, VMware, or UTM, you can use ntoseye configure for easy setup. Otherwise, look at KDNET instructions.
- Power off the Windows VM.
- Run
ntoseye configureand select the hypervisor, virtual machine, and debugger backend. Note theRuncommand it prints. - Start the VM, run the printed guest setup commands in Administrator PowerShell, and reboot.
- Run the command saved in step 2.
Run ntoseye status at any time to inspect configured transports, assigned guest ports, endpoints, and launch commands without changing a VM.
ntoseye configure handles automatic setup for supported libvirt, VMware Workstation, and UTM guests. For plain QEMU or manual configuration, see the KVM/QEMU, VMware, and UTM setup guides.
For any other target, follow the KDNET guide instead; configure is not needed.
See the backend comparison table.
The full documentation is at ntoseye.com. The debugger also documents itself: run ntoseye --help for command-line arguments, press tab in the REPL for completions and descriptions of commands, symbols, and types, and run .hh <command> for a command's full help. The site's command reference is built from that same help.
- Your first session: from attaching to stepping
- Coming from WinDbg: what carries over and what differs
- Troubleshooting
- Using the REPL: command names, aliases
- Expressions: numbers and radix, operators, registers and pseudo-registers, symbols, types, locals
- Breakpoints and watchpoints: the breakpoint grammar, conditions, scoping
- VBS and the Windows hypervisor: VTL1 and trustlet inspection, the hypervisor's partitions, guests, and hypercalls, stops in the hypervisor
- WOW64 processes
- Memory and paging: memory sources, writes, paged-out memory
- Symbols and source: private PDBs,
.sympath/.srcpath, source breakpoints - Choosing a backend: kd/kdnet/gdb/memory comparison, per-hypervisor setup for KVM/QEMU, VMware, and UTM
- KDNET:
kdnet.exeguest setup, host launch, reboot behavior - Crash dumps: offline dump analysis, generating dumps, guest tweaks
- Driver replacement map:
.kdfiles, loading a driver from the host instead of the guest - Python SDK and custom REPL commands
- MCP integration
- Editor integration (DAP): source-level debugging from VS Code, Emacs (dape), or nvim-dap
- Disassembler integration (GDB remote protocol): debugging from IDA, Binary Ninja, Ghidra, gdb, or lldb
Functionality regarding initialization of guest information was written with the help of the following sources: