taskmgr

taskmgr is a small self-hosted Docker container monitor. It reads Docker container metadata, cgroup v2 metrics, and optional GPU telemetry, then serves a password-protected web UI with live charts and history.

The default Compose setup is intended for local administration. It binds to 127.0.0.1, requires you to provide your own password, uses a Docker socket proxy instead of mounting the socket into the app container, and keeps runtime state in a Docker volume.

What It Collects

The SQLite database stores:

• container IDs, names, images, Compose service labels, network mode, cgroup path, init PID, first seen, last seen, and active state
• sampled CPU, memory, pressure stall information, network, disk, and optional GPU metrics
• the password hash and app settings

It does not need your project files, shell history, SSH keys, browser profiles, or other host directories. Do not publish the Docker volume or database unless you are comfortable sharing container names/images from your machine.

Quick Start

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and set a strong password:

   openssl rand -base64 32

   Put the generated value in TASKMGR_PASSWORD. Keep .env private; it is ignored by git and Docker builds.

3. Start the app:

   docker compose up -d --build

4. Open:

   http://127.0.0.1:8080/login
   

Password Changes

To change the password while logged in, open Settings and enter the current and new passwords. A successful change signs out all sessions.

If you forgot the password, run:

./scripts/reset-password.sh

The script prompts without echoing the password, recreates the container once with TASKMGR_PASSWORD_RESET, waits for the app to answer, then recreates it again without the reset secret in the container environment.

You can also reset manually:

TASKMGR_PASSWORD_RESET='new-long-password' docker compose up -d --force-recreate taskmgr
docker compose up -d --force-recreate taskmgr

The second command removes TASKMGR_PASSWORD_RESET from the running container.

Password Files

Instead of storing the bootstrap password in .env, you can set TASKMGR_PASSWORD_FILE to a readable file path. Set exactly one of TASKMGR_PASSWORD or TASKMGR_PASSWORD_FILE.

The same pattern is available for forgotten-password resets:

• TASKMGR_PASSWORD_RESET
• TASKMGR_PASSWORD_RESET_FILE

Network Exposure

By default the service binds to localhost only:

TASKMGR_BIND_IP=127.0.0.1
TASKMGR_PORT=8080

Do not expose taskmgr directly to the public internet. If you need remote access, put it behind a reverse proxy that provides TLS and access control. Only configure TASKMGR_TRUSTED_PROXIES with proxy CIDRs that you control; the app ignores X-Forwarded-For and X-Real-IP from untrusted peers for login rate limiting.

Example for a trusted local reverse proxy:

TASKMGR_TRUSTED_PROXIES=127.0.0.1/32,::1/128,172.16.0.0/12

Optional GPU Metrics

The default Compose file disables GPU collection and does not request GPU devices or PERFMON.

To enable Intel/NVIDIA collectors, start with the GPU override:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build

For NVIDIA, you may also need to uncomment the NVIDIA runtime/deploy block in docker-compose.gpu.yml, depending on your Docker setup.

Configuration

Common environment variables:

Variable	Default	Description
TASKMGR_PASSWORD	empty	Required bootstrap password unless TASKMGR_PASSWORD_FILE is set.
TASKMGR_PASSWORD_FILE	empty	File containing the bootstrap password.
TASKMGR_PASSWORD_RESET	empty	One-shot reset password; remove after use.
TASKMGR_PASSWORD_RESET_FILE	empty	File containing a one-shot reset password.
TASKMGR_BIND_IP	127.0.0.1	Host IP used by Compose port publishing.
TASKMGR_PORT	8080	Host port used by Compose port publishing.
TASKMGR_TRUSTED_PROXIES	127.0.0.1/32,::1/128	CIDRs allowed to supply forwarded client IP headers.
TASKMGR_SAMPLE_FG	1s	Foreground sample interval.
TASKMGR_SAMPLE_BG	5s	Background sample interval.
TASKMGR_GPU_INTEL	false in Compose	Enable Intel GPU collector.
TASKMGR_GPU_NVIDIA	false in Compose	Enable NVIDIA GPU collector.

Development

Host Go is optional. The checked command uses the official Go image:

docker run --rm -v "$PWD:/src" -w /src golang:1.23-bookworm go test ./...

Build the container:

docker build -t taskmgr:dev .

Docker images, CI actions, and downloaded uPlot assets are pinned; Dependabot opens routine update pull requests for supported dependencies.

Check Compose rendering:

TASKMGR_PASSWORD=test docker compose config

Security Notes

This app is a host-monitoring tool. It needs access to host cgroups, host process metadata, and Docker container metadata. The default Compose file:

• uses tecnativa/docker-socket-proxy so the app does not receive the raw Docker socket
• allows only the proxy endpoints needed by taskmgr: containers, events, info
• binds the web UI to localhost by default
• runs the root filesystem read-only with /data as the writable state volume
• drops Linux capabilities by default

Those mitigations do not make taskmgr safe to expose publicly. Treat access to the UI like access to sensitive host inventory.

License

MIT. See LICENSE.