debugwand

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #machine-learning #rust #deep-learning #java #windows #vue #security #mcp #openai

(★ 127)

An *experimental* zero-preparation remote debugger for Python applications running in *local* Kubernetes clusters or Docker containers.

파일 탐색기

최종 버전 다운로드 (.zip)

- - build.yml
  - lint.yml
  - test.yml
  - typecheck.yml
- dependabot.yml
- __init__.py
- attacher.py
- cli.py
- container.py
- debugpy_template.py
- kubernetes.py
- operations.py
- types.py
- ui.py
- hot-reload.md
- troubleshooting.md
- test_k8s.py
- test_operations.py
- test_wand.py
.gitignore
.pre-commit-config.yaml
.python-version
debug.png
LICENSE
pyproject.toml
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://docs.python.org/3/howto/remote_debugging.html) and [debugpy](https://github.com/microsoft/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](docs/troubleshooting.md))

## Quick Start

### Kubernetes

```bash
# 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

```bash
# 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:

```json
{
  "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

| Environment Variable | Description |
|---------------------|-------------|
| `DEBUGWAND_SIMPLE_UI` | Set to `1` for simplified output (useful for Tilt/CI) |
| `DEBUGWAND_AUTO_SELECT_POD` | Set to `1` to auto-select the newest pod |

## Additional Documentation

- **[Hot-Reload Support](docs/hot-reload.md)** - Debugging with uvicorn `--reload` mode
- **[Troubleshooting](docs/troubleshooting.md)** - 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

debugwand

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

debugwand

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README