{"id":38972241,"url":"https://github.com/savannahostrowski/debugwand","last_synced_at":"2026-04-09T04:07:50.669Z","repository":{"id":331731181,"uuid":"1086692406","full_name":"savannahostrowski/debugwand","owner":"savannahostrowski","description":"An *experimental* zero-preparation remote debugger for Python applications running in *local* Kubernetes clusters or Docker containers.","archived":false,"fork":false,"pushed_at":"2026-04-05T15:17:48.000Z","size":209,"stargazers_count":115,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-05T17:13:42.857Z","etag":null,"topics":["debugger","debugging","docker","knative","kubernetes","python","uvicorn"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/debugwand/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/savannahostrowski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T19:08:05.000Z","updated_at":"2026-04-05T15:17:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/savannahostrowski/debugwand","commit_stats":null,"previous_names":["savannahostrowski/debugwand"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/savannahostrowski/debugwand","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savannahostrowski%2Fdebugwand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savannahostrowski%2Fdebugwand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savannahostrowski%2Fdebugwand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savannahostrowski%2Fdebugwand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/savannahostrowski","download_url":"https://codeload.github.com/savannahostrowski/debugwand/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savannahostrowski%2Fdebugwand/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugger","debugging","docker","knative","kubernetes","python","uvicorn"],"created_at":"2026-01-17T16:40:41.390Z","updated_at":"2026-04-09T04:07:50.656Z","avatar_url":"https://github.com/savannahostrowski.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# debugwand 🪄\n\nA zero-preparation remote debugger for Python applications running in Kubernetes clusters or Docker containers.\n\n*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)*\n\n\u003e Note: `debugwand` is experimental and not made for production. Use at your own risk.\n\n## Features\n\n- **Zero-preparation debugging** - No code changes or restarts required\n- **Full breakpoint debugging** - Using `debugpy`\n- **Kubernetes-native** - Handles pod discovery, service routing, and Knative\n- **Container support** - Debug Python processes in local Podman or Docker containers\n- **Process selection** - Interactive selection with CPU/memory metrics\n\n## Requirements\n\n- **Python 3.14+** on both local machine and target\n- **debugpy** installed in the target container\n- **kubectl** (for Kubernetes) or **Docker CLI** (for containers)\n- **SYS_PTRACE capability** - on Linux/containers (see [troubleshooting](docs/troubleshooting.md))\n\n## Quick Start\n\n### Kubernetes\n\n```bash\n# List pods and Python processes\nwand pods -n my-namespace -s my-service --with-pids\n\n# Debug a live process\nwand debug -n my-namespace -s my-service\n```\n\n### Docker/Podman\n\n```bash\n# Debug a container (must have SYS_PTRACE capability)\nwand debug --container my-container\n```\n\n\u003e Containers must be started with `--cap-add=SYS_PTRACE` and `-p 5679:5679`\n\n### Connect your editor\n\n**VSCode** launch configuration:\n\n```json\n{\n  \"name\": \"Attach to debugwand\",\n  \"type\": \"debugpy\",\n  \"request\": \"attach\",\n  \"connect\": { \"host\": \"localhost\", \"port\": 5679 },\n  \"pathMappings\": [{ \"localRoot\": \"${workspaceFolder}\", \"remoteRoot\": \"/app\" }]\n}\n```\n\n**Other DAP clients**: Connect to `localhost:5679`\n\n## Configuration\n\n| Environment Variable | Description |\n|---------------------|-------------|\n| `DEBUGWAND_SIMPLE_UI` | Set to `1` for simplified output (useful for Tilt/CI) |\n| `DEBUGWAND_AUTO_SELECT_POD` | Set to `1` to auto-select the newest pod |\n\n## Additional Documentation\n\n- **[Hot-Reload Support](docs/hot-reload.md)** - Debugging with uvicorn `--reload` mode\n- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions\n\n## How it works\n\n```\n┌─────────────────┐                            ┌────────────────────┐\n│  Local Machine  │                            │   Pod / Container  │\n│                 │                            │                    │\n│  debugwand CLI  │◄─ kubectl/docker/podman ─► │   Python App       │\n└────────┬────────┘                            └────────┬───────────┘\n         │                                              │\n         │ 1. Discover pods (k8s only)                  │\n         ├─────────────────────────────────────────────►│\n         │                                              │\n         │ 2. List Python processes                     │\n         ├─────────────────────────────────────────────►│\n         │                                              │\n         │ 3. Select process                            │\n         │                                              │\n         │ 4. Inject debugpy via                        │\n         │    sys.remote_exec()                         │\n         ├─────────────────────────────────────────────►│\n         │                                              │\n         │                            5. debugpy.listen()\n         │                               ┌──────────────┤\n         │ 6. Port-forward (k8s)         │              │\n         │    or exposed port            │              │\n         │◄──────────────────────────────┼─────────────►│\n         │    localhost:5679             │              │\n         │                               └──────────────┤\n         │ 7. Connect editor                            │\n         ├──────────────────────────────────────────────┤\n         │         Debugging Session                    │\n         │◄────────────────────────────────────────────►│\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavannahostrowski%2Fdebugwand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsavannahostrowski%2Fdebugwand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavannahostrowski%2Fdebugwand/lists"}