dockpeek

Peek at your Docker containers from the terminal — status, health, ports, CPU and memory in one color-coded glance. Local or remote. Zero dependencies, just Python and the docker CLI.

Why

Almost everything I run lives in a container, spread across a Raspberry Pi and a home server. docker ps tells me the truth but wraps into an unreadable mess the moment there are more than a handful of containers, and it buries the two things I actually care about: is anything unhealthy, and is anything stuck restarting? dockpeek answers that in one screen — sorted, aligned, color-coded — and it works against a remote daemon over SSH, so I can check either machine without logging in.

It rounds out a small family of terminal tools: pulse watches the machine, dockpeek watches the containers, upcheck watches the sites, and coinpeek watches the market.

Install

git clone https://github.com/0iroN/dockpeek.git
cd dockpeek

That's it — no pip install. It only uses the Python standard library and shells out to docker.

Usage

python dockpeek.py                        # running containers
python dockpeek.py -a                     # include stopped ones
python dockpeek.py -s                     # add CPU and memory
python dockpeek.py -H ssh://user@server   # inspect a remote daemon
python dockpeek.py -w 5                   # live view, refreshing every 5s

-H is passed straight to docker -H, so anything the Docker CLI understands works: ssh://user@host, tcp://host:2375, or a socket path. The DOCKER_HOST environment variable is honored too.

Example

  dockpeek  · 6 container(s) · 21:04:11

  ● api            Up 3 days               healthy    8080→8000
  ● postgres       Up 3 days               healthy    5432/tcp
  ● redis          Up 3 days                          6379/tcp
  ● worker         Up 5 seconds            starting
  ○ migrate        Exited (0) 5 days ago
  ○ flaky-thing    Restarting (1) 20 sec…

  4 running · 2 not running

Running containers are green and sorted first; anything restarting, paused, or still starting up is yellow; stopped and UNHEALTHY containers are red. Port mappings are condensed — the IPv4 and IPv6 duplicates that docker ps prints collapse into a single 8080→8000.

Exit codes

Handy in a cron job or a monitoring script:

Code	Meaning
0	Everything queried is fine
1	At least one container reports unhealthy
2	Docker isn't installed, isn't running, or the host is unreachable

python dockpeek.py || notify-send "a container is unhealthy!"

Notes

• Health only shows for containers that define a HEALTHCHECK; the column stays blank otherwise.
• -s runs docker stats --no-stream, which takes a moment on a busy host — that's why it's opt-in.
• --watch enforces a minimum 1-second interval.
• The daemon is never contacted directly; everything goes through the docker CLI, so your existing contexts, sockets, and SSH config keep working.

License

MIT © Osman Demir · osmandemir.net