debux

debux is an open-source container debugger designed for Docker and Kubernetes environments. It addresses a common pain point: debugging production-style containers that lack shells or package managers, such as distroless, scratch, and minimal images. Unlike `docker exec`, which requires tools and a shell inside the target image, debux starts a separate debug toolbox container that attaches to the target, shares useful namespaces (network, process), and exposes the target filesystem at `$DEBUX_TARGET_ROOT` (usually `/proc/1/root`). Key capabilities include: - **Works with any container**: Debugs running, stopped, exited, or crash-looping containers, including those without shells or package managers. - **Docker and Kubernetes support**: Unified workflow for local Docker containers, Docker Compose services, Podman containers, and Kubernetes pods. Also supports debugging Kubernetes nodes with host-namespace access. - **Ready-to-use toolbox**: Pre-installed tools include curl, wget, dig, nmap, tcpdump, strace, ltrace, gdb, htop, vim, jq, git, openssh, zsh, tmux, and more. The toolbox is based on Wolfi and uses mise for package management. - **On-demand tool installation**: The `dctl` command installs additional tools during a debug session using mise. Tools can be preloaded at session start with `--tools`. - **Target-aware shell**: Jump into the target root, inspect target processes, reuse the target network namespace, and run the target's own binaries via chroot when the toolbox lacks them. - **Port forwarding and file copying**: Reach and pull files from any target, even containers started without `-p` and distroless pods where `kubectl cp` fails. - **Kubernetes copy mode**: When ephemeral containers are blocked by RBAC or admission policy, `--copy` creates a temporary duplicate pod for debugging. Supports long-lived copy sessions with TTL, Karpenter protection, and reattach capabilities. - **Node debugging**: `debux node` schedules a host-namespace toolbox pod on a Kubernetes node, mounting the node root filesystem and sharing PID, network, and IPC namespaces. - **Image debugging**: Debug an image without starting it, useful when the image itself cannot boot. - **TUI interface**: Full-screen target browser with Docker, Kubernetes context/namespace navigation, active session reattach, recent sessions, and option toggles. - **Shell completion**: Generated completions include live Docker and Kubernetes targets with substring matching. The tool is distributed as a single binary with an installer script that supports Linux and macOS on amd64/arm64. Release assets are checksum-verified, and optional cosign signature verification is supported. The project is licensed under MIT.