ntdrive

Where

Switch

What it does

guest

setup-guest.cmd -NoAccount

use your own Windows account for SSH instead of creating ntdrive

guest

setup-guest.cmd -NoStandard

skip ntdrive-user (created by default, a plain account for term_open account=standard)

guest

setup-guest.cmd -OpenSshZip <file or URL>

OpenSSH from the Win32-OpenSSH zip, for a guest without internet (Insider builds have no capability package, and the script falls back to a download on its own)

guest

setup-guest.cmd -Serial

serial named-pipe transport instead of KDNET

host

setup-host.cmd -Verify

only the end-to-end check

host

setup-host.cmd -FirewallOnly

manual repair of the KDNET firewall rules, from an Administrator shell

host

ntdrive setup --transport serial

serial transport for a host where nobody can approve a UAC prompt, then ntdrive kd setup-host <vm> with the VM off

Tool

Effect

What it does

vm_upgrade_builds

read

List Windows 11 Insider Preview builds (amd64) that vm_upgrade can install, newest first, from the UUP dump API.

vm_upgrade

destructive

Upgrade a running guest in place to a Windows Insider build. The guest downloads the build from Microsoft, builds setup media and runs setup.exe as SYSTEM, which reboots it several times over 30 to 90 minutes. Returns at once: poll vm_upgrade_status. Edition and language follow the guest. Take a snapshot first, and kd_detach (refused while kd is attached). Needs 30 GB free on C:. confirm=true.

vm_upgrade_status

read

Where a vm_upgrade stands: building (with the step), upgrading, offline (setup is between reboots), done, failed (with setup's own error lines), interrupted or none. When done it names the steps that finish the job: kd_setup_guest, vm_reboot, kd_attach, a snapshot.

vm_list

read

List registered VMs with power, debugger and terminal state.

vm_state

read

Power, debugger and terminal state of one VM.

vm_wait_ready

read

Wait until the guest is back up: block until SSH answers, or the timeout passes. For after a reboot or a bugcheck's auto-restart, so no manual polling loop is needed.

vm_start

additive

Power on (or resume) a VM without the GUI by default. discard_saved_state boots fresh when a stale saved state blocks the resume.

vm_stop

destructive

Stop the VM: mode soft, hard or kill. hard and kill need confirm=true.

vm_reboot

destructive

Reboot the guest (soft, hard or from the debugger) and bring kd and terminals back, the terminals under new session ids. The guest comes back running rather than frozen at a kd> prompt, so file_* and con_run work straight away. hard needs confirm=true.

vm_suspend

additive

Suspend the VM to disk.

vm_resume

additive

Resume a suspended VM (same as vm_start).

vm_config

additive

Read or change the VM hardware in the vmx: cpus, memory_mb, nic. Without arguments it reports the current values. A change needs the VM powered off.

snap_list

read

Snapshot tree of a VM plus the current snapshot and stored metadata. retention classes each snapshot kept, temporary, expired or unclassified, and disk gives the free space on the VM drive and the expired snapshots snap_prune would delete.

snap_take

additive

Take a snapshot (memory included while running), record description and kd state, and return the snapshot list. A name that already exists is reported with created=false instead of erroring, and replace=true deletes it and retakes.

snap_revert

destructive

Revert to a snapshot: detach kd, revert, start, reattach kd, reopen terminals. The guest comes back running, not frozen at a kd> prompt, so the file_push and con_run that follow a revert work straight away (kd_break freezes it again when that is what you want).

snap_delete

destructive

Delete a snapshot (and optionally its children). Needs confirm=true.

snap_keep

additive

Mark a snapshot kept (never pruned) or temporary (expires, then snap_prune may delete it). Use it on a snapshot snap_list calls unclassified, or to pin a temporary one you still need.

snap_prune

destructive

Delete the expired temporary snapshots of a VM (snap_list names them under disk.prune_candidates) and report the space it got back. Never touches kept, unclassified or current snapshots. Needs confirm=true.

kd_setup_host

additive

Prepare the host side of the kd transport: serial adds the named-pipe COM port to the vmx (VM must be off), net checks the host firewall for kd.exe and repairs it through one UAC prompt.

kd_setup_guest

additive

Enable kernel debugging in the guest with bcdedit over SSH (serial or KDNET per kd_transport) and save the KDNET port and key to vms.yaml. Settings that already point at this host are read back, not rewritten.

kd_attach

additive

Start kd.exe for the VM and wait until the target connects.

kd_detach

additive

Resume the target if needed and stop kd.exe.

kd_break

additive

Break into the running target and wait for the kd> prompt.

kd_go

additive

Resume the target (g).

kd_exec

destructive

Run one or more debugger commands at the kd> prompt and return each command's output. A running target (right after kd_attach, or after kd_go) is broken into first, so the first command no longer fails with kd_not_broken. A symbol-heavy command (x, u, ln, lm, a first !extension) or a processor switch can be slow while symbols download: over a network symbol path the first lookup blocks on the server, so set a cache-only path (.sympath cache*C:\symbols) or pre-fetch (.reload /f) once symbols are cached. Raise the timeout, and if one wedges ntdrive interrupts it so the next kd_exec works (at a bugcheck the interrupt keeps the break, but do not kd_detach there: detaching resumes and reboots). A breakpoint that resumes itself (gc) on a hot path NMIs the guest over KDNET: use kd_sample.

kd_bugcheck

read

Classify the current bugcheck cheaply: runs .bugcheck (two lines) and returns the code, its arguments and the faulting instruction. Use this before !analyze -v, which takes tens of seconds and prints tens of kilobytes of chkimg noise that is false on a patched kernel.

kd_symcheck

read

Say whether the loaded symbols can actually answer: resolves a type (dt) and a function name (x) and reports each separately, with the current symbol path. A cached PDB that has function names but no type information makes !pool, !process and dt all fail with bad symbols at once, which reads like the commands being wrong rather than the PDB being incomplete. Run this the first time a symbol-dependent command misbehaves. Over a network symbol path the first lookup can block, so attach with symbol_path=cache*C:\symbols on a host with no symbol server.

kd_capture_fault

destructive

Capture an OOB-write or fault bugcheck in one call: switch to the processor the bugcheck broke on, find the KTRAP_FRAME on the stack by the faulting RIP (bugcheck Arg3 by default) and .trap it (or .cxr a context_record), then return the unwound call stack (kb), the faulting instruction and the kernel module bases (lm). Needs a bugcheck break (kd_wait_event catches one). It sets a cache-only symbol path first so the symbol-heavy commands cannot wedge on a network symbol server and drop the target mid-capture (cache_symbols=false keeps the current path). Pass fault_rip or context_record for bugchecks that do not carry the fault address in Arg3. Do not kd_detach or kd_go afterwards to leave: both resume and complete the crash, losing the bugcheck.

kd_sample

destructive

Break on a symbol, let the target run, and collect the value of one or more expressions at each of the next n hits, then clear the breakpoint. Replaces a manual bp/g/eval round trip per hit. The breakpoint is plain and conditions are evaluated by the daemon, never compiled into the breakpoint, because a conditional breakpoint with gc on a hot function NMIs the guest.

kd_wait_event

read

Wait until the running target stops (bugcheck, breakpoint, ...) or the timeout expires.

kd_state

read

Debugger state: attached (kd.exe alive), state (detached, waiting, running, broken), transport, target info, last event and log path.

kd_log_tail

read

Last bytes of the kd.exe transcript.

term_open

additive

Open a real-time PTY session (SSH) on the guest and return its session_id.

term_send

destructive

Type text and/or keys into a session and return at once. Tokens: {enter} {tab} {esc} {ctrl+c} {up}. Use it for a long-running command or one that will stop in the debugger, then term_read or kd_wait_event.

term_read

read

Read new output (delta), wait for a regex (until), or render the screen (mode=screen). A wait ends with guest_frozen_by_debugger when the target stops at kd>. The PTY echoes what was typed, so an until that the sent command line also contains (echo ===END=== waited on with ===END===) matches that echo and returns before the command ran: pass skip_echo=true, or let term_exec frame the command, which it does by splitting its marker so the echo cannot carry it.

term_exec

destructive

Run one command in the session, wait for it to end (up to timeout) and return only its output and exit code. For a command that will stop in the kernel debugger or drop SSH, use term_send, then kd_wait_event or term_read.

term_kill

destructive

Stop whatever the session's shell is running, keeping the session open. Use it when a command will not end and {ctrl+c} did not help: ctrl+c is a console control event that a program may ignore, and a program that ignores it keeps holding the shell so every later term_exec queues behind it. Each direct child of the shell is killed with its whole tree, so a run that spawned workers leaves no orphan. The shell itself is never killed. It runs over a separate SSH channel, so a busy PTY does not block it.

term_resize

additive

Resize the PTY.

term_close

additive

Close a session.

term_list

read

List the usable terminal sessions (their ids are in open, with each one's shell) and the CoView page that mirrors them live in a browser (#<session_id> selects one). Closed and disconnected sessions are only counted, not listed: they pile up as snap_revert and reboot replace the open ones, and dumping hundreds of them once cost a caller its whole token budget. include_closed=true lists them, term_prune forgets them.

term_prune

additive

Forget closed and disconnected terminal sessions (their open successors stay), so the list shows only what is usable.

con_screenshot

read

Save a PNG of the VM console and return its path (base64 on request). method=vnc reads the console framebuffer without any guest login (con_enable_vnc turns VNC on first).

con_send_keys

destructive

Type keys into the VM console over VNC, no guest login needed (con_enable_vnc turns VNC on). For a lock or login screen or before the network is up: keys=['{password}', '{enter}'] logs in without the password crossing the wire.

con_click

destructive

Click the VM console at a framebuffer pixel over VNC, no guest login needed. Read the coordinate off con_screenshot method=vnc (same pixels), for example to pick a user tile on the lock screen, then con_send_keys for the password.

con_autologon

additive

Configure Windows automatic logon in the guest so a reboot lands on an unlocked interactive desktop (session 1), which term_* over SSH (session 0) cannot open. enabled=false clears it. needs_reboot: run vm_reboot mode=soft next.

con_run

destructive

Run a command on the guest's interactive desktop (session 1) and return its output, for GUI or session-bound programs that SSH in session 0 cannot open. It runs through a scheduled task in the logged-on user's session, so the account must be logged in (con_autologon). A missing session fails fast at launch with that hint. shell=powershell carries the text as -EncodedCommand so $vars and quotes need no quoting. detach=true starts it and returns at once, leaving it running.

con_enable_vnc

additive

Turn on the console VNC server in the vmx so con_screenshot method=vnc can read the screen without a guest login. Run it with the VM off, then start the VM.

file_push

destructive

Copy a file, directory or glob from the host into the guest, flush it to the guest's disk and verify it by SHA-256 (over SFTP, or through VMware Tools when SSH is down). Fails with verify_failed when the copy does not match, so a corrupt push cannot read as success.

file_pull

additive

Copy a file from the guest to the host and check its size, failing with verify_failed when the host copy is short.

file_stat

read

Size, last-modified time and is_dir of a guest path, so freshness can be checked without a shell. exists=false when the path is not there.

file_ls

read

List a guest directory (each entry name, size, modified, is_dir), without a shell.

file_delete

destructive

Delete a guest file or directory (recurse for a non-empty directory). deleted=false when it was already absent.

sys_state

read

VM power, debugger state, terminal sessions and last events in one answer.

sys_health

read

Check binaries, config and backend capabilities, then probe every VM: power, guest SSH port and the debugger transport on the host. Run this first: ok is false when the host or any VM has an issue, and every issue names its fix.

File

Read it if you are

README.md

a human setting up or using ntdrive

SKILL.md

an agent using the tools. State model, standard procedures, and moves to avoid

AGENTS.md

any coding agent changing this repo. Conventions, commands and where things live

CLAUDE.md

Claude Code. Points at AGENTS.md and adds the Claude-specific bits

PRD.md

anyone who wants the full requirements and design rationale

vms.example.yaml

someone editing vms.yaml by hand: every field, documented

policy.example.yaml

someone tuning the allow, confirm, deny level per tool

scripts/

host and guest setup, see Setup above