# docker-debug attaches a second container to the namespaces of a running one

> docker-debug is a small Go CLI that starts a new container inside the process, network, user, filesystem and IPC namespaces of a container that is already running, so you can use tools that were never installed in the production image. It borrows its idea from a Kubernetes debug plugin, and its todo list shows the project is not finished.

**zeromake/docker-debug** — use new container attach on already container go on debug

- Repository: https://github.com/zeromake/docker-debug
- Stars: 639 · Forks: 40
- Language: Go
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/zeromake-docker-debug

## A second container, same namespaces

docker-debug is a troubleshooting tool for a running Docker container, and it works by running a new container in the namespaces of the target. The new container joins the process, network, user, filesystem and IPC namespaces of the container you are investigating, and the stated benefit is that you can use arbitrary troubleshooting tools without pre-installing them in your production container image. That is the problem it solves, and the problem is real. A production image is usually built to be small, so it has no shell worth using, no network utilities, no debugger and no way to look at the process tree. The usual answers are to rebuild an image with a debugger in it, which means a rebuild and a redeploy, or to exec into the container, which only gives you what is already inside it. Joining the namespaces sidesteps both. The README credits the idea to a Kubernetes debug plugin, and the filesystem approach to a post on the internals of Docker, and the project also points at the Docker engine API documentation, which is what it drives the daemon with.

## The default image is netshoot, and a config file can change it

The tool ships with a sensible default image and a configuration file that lets you replace it. The default is nicolaka/netshoot, a well known network troubleshooting image, and you can override it with a command line flag or, as the README puts it, better, with a configuration file at the path for the per user configuration directory.

```toml
version = "0.7.5"
image = "nicolaka/netshoot:latest"
mount_dir = "/mnt/container"
timeout = 10000000000
config_default = "default"

[config]
  [config.default]
    version = "1.40"
    host = "unix:///var/run/docker.sock"
    tls = false
    cert_dir = ""
    cert_password = ""
```

The file carries a few more things than the image. There is a version field, which the todo list refers to as version management for the config file, so the format can change without breaking an existing configuration. There is the mount directory, which is where the target container's filesystem is made available, and there is a timeout. The named configuration block holds the Docker connection details, with a host that defaults to the standard unix socket, a TLS switch, and a certificate directory and password for remote daemons with TLS enabled. The named config system is what lets you keep several daemons in one file, and the CLI can also take the connection settings directly, which the todo list records as the docker connection config on cli command feature.

## Six steps from a container name to a shell

The details section of the README lays out the sequence, and it is short enough to hold in your head. The tool finds the image, pulling it if it is not present, and finds the container by name, returning an error if there is no such container. From a customisable image it runs a new container in the target container's namespaces, including the IPC, process and network namespaces and the filesystem, with standard input held open. It then creates and runs an exec on that new container, which is where you do the debugging. When you are finished, it waits for the debug container to exit and cleans up. The ordering matters in one respect, because the target filesystem is mounted rather than shared, so what you see under the mount directory is the state of the target filesystem as it was, and a write there changes the target container's files. The todo list records that the CLI can set the mount target for the container filesystem and that volume filesystems can be mounted, so the mount behaviour is configurable rather than fixed.

## Three ways to install it

Installation is a Homebrew tap, a release binary, or a build from source. The brew line is one command.

```shell
brew install zeromake/docker-debug/docker-debug
```

The release route fetches the latest tag first, then downloads the binary for the platform, with separate artefacts for Intel macOS, Apple silicon, Linux and Windows. The Linux path looks like this.

```shell
curl -Lo docker-debug https://github.com/zeromake/docker-debug/releases/download/${VERSION}/docker-debug-linux-amd64
chmod +x ./docker-debug
sudo mv docker-debug /usr/local/bin/
```

The README also provides a fish version of the same commands, which is the sort of detail that suggests the author actually uses it. Building from source is two commands.

```shell
go build -o docker-debug ./cmd/docker-debug
mv docker-debug /usr/local/bin
```

The Makefile wraps the same thing with targets for a Linux binary, a Linux ARM 64 binary, and a UPX compressed variant, each delegating to a script in the scripts directory, and it prints a warning that the default target produces a Linux executable and that macOS or Windows need the cross build. The module file asks for Go 1.25.0, and the dependency list is the interesting part for anyone reading the code, with the Docker engine client, cobra for the command line, logrus for logging, a TOML parser for the configuration, a semver library for the version handling and the moby terminal package.

## The command surface is small, and the todo list is honest

The usage is two forms, a container name followed by a command, and a help flag, plus an info command that reports the tool's own configuration.

```shell
# docker-debug [OPTIONS] CONTAINER COMMAND [ARG...] [flags]
docker-debug CONTAINER COMMAND
# More flags
docker-debug --help
# info
docker-debug info
```

The project keeps a todo list in the readme, and reading it tells you what to expect. Done are Windows 7 support under Docker Toolbox, a changelog, a Chinese readme, the brew package, config file version management, setting the mount target for the container filesystem, mounting volume filesystems, taking the Docker connection settings on the command line, and support for volume flags. Still open are Windows 10 support, a refactoring of the code, adding testing, smooth exit on signals, documenting the CLI commands and the config file in the readme, and an HTTP API with a web shell. The absence of tests and the refactoring item are the two that matter for a tool you might script against, and the missing documentation of the command line and config file is a real gap for anyone who wants to use the flags seriously rather than the default invocation.

## How it compares with the Kubernetes equivalent

The comparison point the project itself names is a Kubernetes debug plugin, and the difference is instructive. In Kubernetes the equivalent operation attaches an ephemeral container to a pod in the cluster, and the tooling around it is mature enough to be a default command. docker-debug is the Docker Engine equivalent of that idea, and it is at an earlier stage, with no release notes beyond a changelog, an open refactoring item and no test suite. It is also a single static binary in Go, with no daemon, no agent and no server component, which is what makes it practical to drop onto a machine during an incident. The permissions requirement is the thing to think about before you install it anywhere sensitive. Joining the namespaces of another container means the debug process sees that container's processes, its network and its files, and the tool talks to the Docker daemon over a socket, which on a default Linux install means root on the host. That is the price of not rebuilding your image, and it is a price worth paying for a genuine incident and a bad idea to make permanent.

## Conclusion

docker-debug suits an operator facing a production container they cannot rebuild, because the whole point is that the debug image can carry tools the running image does not have, and the namespace join gives you the process list, the network and the filesystem of the target. It is the wrong tool if the container is disposable and you can simply start a new one with a debug image, and the wrong tool if you need a permanent sidecar or a web shell, since an HTTP API and a web shell are still open items. Verify three things before you reach for it: that your Docker daemon exposes a socket you are willing to point a privileged helper at, since the configuration defaults to the standard unix socket, that the target container is running, because the tool looks up the container by name and errors out if it does not exist, and that the debug image you choose can run in your kernel namespaces, which rules out some minimal images. The licence is MIT, the newest release is v0.7.11 from 2025-09-21, and the last push was on 2026-09-18.

## FAQ

### What does docker-debug do to a running container?

It runs a new container in the process, network, user, filesystem and IPC namespaces of the target container, then creates an exec on that new container so you can use troubleshooting tools that are not installed in the production image. It waits for the debug container to exit and cleans up afterwards.

### Which image does docker-debug use by default?

The default is nicolaka/netshoot, and you can override it with a command line flag or with the config file at the per user configuration directory, which also holds the version, the mount directory, a timeout and the named Docker connection settings.

### How do I install docker-debug?

With Homebrew using the tap, by downloading the release binary for your platform and moving it onto your PATH, or by building it from source with go build against the cmd/docker-debug package. The module requires Go 1.25.0.

### Is docker-debug finished?

Not entirely. The readme todo list still has Windows 10 support, a code refactoring, adding tests, smooth exit on signals, documentation of the CLI commands and the config file, and an HTTP API with a web shell marked as open.

## Sources

- [Issues](https://github.com/zeromake/docker-debug/issues)
- [License: MIT](https://github.com/zeromake/docker-debug/blob/master/LICENSE)
- [README](https://github.com/zeromake/docker-debug/blob/master/README.md)
- [Releases](https://github.com/zeromake/docker-debug/releases)
- [zeromake/docker-debug on GitHub](https://github.com/zeromake/docker-debug)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zeromake-docker-debug