ntoseye

A WinDbg-like Windows debugger for Linux and macOS, with support for kernel-mode and user-mode debugging in virtual machines and offline crash-dump analysis.

Showcase

Debugging via REPL	Debugging via VSCode + DAP

Features

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
Python SDK and custom commands
Editor integration over DAP
Agent integration over MCP

Supported Windows

ntoseye supports 64-bit AMD64 and ARM64 Windows 10 and 11 targets.

Supported hypervisors

ntoseye supports any hypervisor, cloud VM, or physical machine reachable over KDNET. KVM/QEMU, VMware Workstation, and UTM guests additionally get KDCOM, GDB, and memory-only backends.

Disclaimer

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/images/ for binaries downloaded from the VM
~/.ntoseye/symbols/ for PDBs
~/.ntoseye/aliases for command aliases
~/.ntoseye/history for persistent REPL history

Getting started

Install via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dmaivel/ntoseye/releases/latest/download/ntoseye-installer.sh | sh

Prebuilt release binaries include the CLI and MCP server but omit embedded Python for portability. Use a Cargo or source build for in-REPL Python commands; the standalone pip install ntoseye SDK needs neither.

Install via cargo

cargo install ntoseye

cargo install and default source builds enable embedded Python and link against the local Python installation.

Install the Python SDK

For standalone debugger automation from Python on Linux or Apple Silicon macOS:

pip install ntoseye

The Python package exposes the debugger through import ntoseye; it does not install the ntoseye CLI. See the Python SDK documentation.

Building

git clone https://github.com/dmaivel/ntoseye.git
cd ntoseye
cargo build --release

To build without embedded Python:

cargo build --release --no-default-features --features cli,mcp

Usage

Quickstart

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 configure and select the hypervisor, virtual machine, and debugger backend. Note the Run command it prints.
Start the VM, run the printed guest setup commands in Administrator PowerShell, and reboot.
On Linux, allow ntoseye to inspect the hypervisor process. This resets on reboot:
```
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
```
Alternatively, prefix the printed Run command with sudo.
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.

Hypervisor setup

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 hypervisor, a cloud VM, or a physical machine, follow the KDNET guide instead; configure is not needed.

Not sure which backend to use?

See the backend comparison table.

Documentation

The debugger is self-documented: run ntoseye --help for command-line arguments, and press tab in the REPL for completions and descriptions of commands, symbols, and types.

REPL usage: expressions, radix, breakpoints, watchpoints, aliases
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.exe guest setup, host launch, reboot behavior
Crash dumps: offline dump analysis, generating dumps, guest tweaks
Python SDK and custom commands
MCP integration
Editor integration (DAP): source-level debugging from VS Code, Emacs (dape), or nvim-dap

Credits

Functionality regarding initialization of guest information was written with the help of the following sources:

ntoseye 0.28.0