debugwand 🪄

A zero-preparation remote debugger for Python applications running in Kubernetes clusters or Docker containers.

Made possible by the Python 3.14 remote debugging attachment protocol and debugpy

Note: debugwand is experimental and not made for production. Use at your own risk.

Features

• Zero-preparation debugging - No code changes or restarts required
• Full breakpoint debugging - Using debugpy
• Kubernetes-native - Handles pod discovery, service routing, and Knative
• Container support - Debug Python processes in local Podman or Docker containers
• Process selection - Interactive selection with CPU/memory metrics

Requirements

• Python 3.14+ on both local machine and target
• debugpy installed in the target container
• kubectl (for Kubernetes) or Docker CLI (for containers)
• SYS_PTRACE capability - on Linux/containers (see troubleshooting)

Quick Start

Kubernetes

# List pods and Python processes
wand pods -n my-namespace -s my-service --with-pids

# Debug a live process
wand debug -n my-namespace -s my-service

Docker/Podman

# Debug a container (must have SYS_PTRACE capability)
wand debug --container my-container

Containers must be started with --cap-add=SYS_PTRACE and -p 5679:5679

Connect your editor

VSCode launch configuration:

{
  "name": "Attach to debugwand",
  "type": "debugpy",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5679 },
  "pathMappings": [{ "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }]
}

Other DAP clients: Connect to localhost:5679

Configuration

Additional Documentation

• Hot-Reload Support - Debugging with uvicorn --reload mode
• Troubleshooting - Common issues and solutions

How it works

┌─────────────────┐                            ┌────────────────────┐
│  Local Machine  │                            │   Pod / Container  │
│                 │                            │                    │
│  debugwand CLI  │◄─ kubectl/docker/podman ─► │   Python App       │
└────────┬────────┘                            └────────┬───────────┘
         │                                              │
         │ 1. Discover pods (k8s only)                  │
         ├─────────────────────────────────────────────►│
         │                                              │
         │ 2. List Python processes                     │
         ├─────────────────────────────────────────────►│
         │                                              │
         │ 3. Select process                            │
         │                                              │
         │ 4. Inject debugpy via                        │
         │    sys.remote_exec()                         │
         ├─────────────────────────────────────────────►│
         │                                              │
         │                            5. debugpy.listen()
         │                               ┌──────────────┤
         │ 6. Port-forward (k8s)         │              │
         │    or exposed port            │              │
         │◄──────────────────────────────┼─────────────►│
         │    localhost:5679             │              │
         │                               └──────────────┤
         │ 7. Connect editor                            │
         ├──────────────────────────────────────────────┤
         │         Debugging Session                    │
         │◄────────────────────────────────────────────►│

License

MIT