ntoseye

WinDbg-like kernel debugger for Windows, from Linux and macOS.

Features

WinDbg-compatible REPL commands and hexadecimal expression radix
Kernel and usermode debugging
Remote debugging over encrypted KDNET
Public/private PDB symbols, source lines, and scoped local-variable metadata
Deferred, conditional, pass-count, one-shot, and command-action breakpoints
Hardware watchpoints
Integrated bugcheck, exception, verifier, WHEA, and crash-dump analysis
Four backends: Windows KDCOM and KDNET, QEMU's GDB stub, and passive memory introspection
Python SDK and custom commands
MCP integration

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 the 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

Preview

ntos

Installation

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

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 behaviour
Crash dumps: offline dump analysis, generating dumps, guest tweaks
Python SDK and custom commands
MCP integration

Credits

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

ntoseye 0.26.0