Docker Tracker

Docker Tracker

When enabled with --docker, Knightwatch connects to the Docker daemon and tracks all containers in real time, exposing snapshots via the /docker family of endpoints. It also emits lifecycle events to the Telegram bot and webhook dispatcher.

knightwatch --docker

---

Endpoints

Endpoint	Description
GET /docker-containers	List snapshots of all currently tracked containers
GET /container/<id_or_name>	Full snapshot of a single container by ID or name, or 404 if not found
GET /top-containers	Top N containers sorted by CPU or memory (requires --docker)

Top Containers

GET /top-containers?sort=cpu&limit=10

The sort parameter accepts cpu or memory. limit defaults to all containers if omitted.

---

Container Commands

When the server is started with --allow-docker-commands, the following write endpoints become available. These endpoints are not read-only — they actively affect running containers.

Authentication required. All container command endpoints always require authentication, regardless of whether --enable-auth is set. The auth session endpoints are automatically enabled alongside --allow-docker-commands.

knightwatch --docker --allow-docker-commands

Command Endpoints

Endpoint	Description
POST /docker/stop-container	Stop a container, with an optional timeout before killing it
POST /docker/kill-container	Send a signal to a container
POST /docker/start-container	Start a container
POST /docker/restart-container	Restart a container, with an optional timeout
POST /docker/pause-container	Pause (freeze) a container
POST /docker/unpause-container	Resume a paused container
POST /docker/poll/pause	Pause the polling loop
POST /docker/poll/resume	Resume the polling loop
POST /docker/poll/interval	Change the polling interval

Stopping a Container

Stops a container gracefully, with an optional timeout in seconds before it is forcefully killed:

POST /docker/stop-container
Content-Type: application/json
 
{ "id_or_name": "my-container", "timeout_secs": 10 }

Killing a Container

Sends a signal to a container by ID or name:

POST /docker/kill-container
Content-Type: application/json
 
{ "id_or_name": "my-container", "signal": "SIGKILL" }

Starting and Restarting

Start a stopped container:

POST /docker/start-container
Content-Type: application/json
 
{ "id_or_name": "my-container" }

Restart a running or stopped container, with an optional pre-kill timeout:

POST /docker/restart-container
Content-Type: application/json
 
{ "id_or_name": "my-container", "timeout_secs": 5 }

Pausing and Unpausing

Freeze all processes in a container:

POST /docker/pause-container
Content-Type: application/json
 
{ "id_or_name": "my-container" }

Resume a paused container:

POST /docker/unpause-container
Content-Type: application/json
 
{ "id_or_name": "my-container" }

Controlling the Poll Loop

Pause snapshot collection (the tracker still responds to queries and commands):

POST /docker/poll/pause

Resume at the current interval:

POST /docker/poll/resume

Change the polling interval (takes effect immediately):

POST /docker/poll/interval
Content-Type: application/json
 
{ "interval_ms": 2000 }

---

Webhook Events

Event	Description	Key data fields
docker.initial_snapshot	First capture after startup	container_count, containers
docker.containers_appeared	New containers detected	container_count, containers
docker.containers_disappeared	Containers no longer visible	container_count, containers
docker.container_status_changed	A container's status changed	id, name, image, status, previous_status
docker.container_health_changed	A container's health status changed	id, name, image, health, previous_health
docker.container_oom_killed	A container was killed by the OOM killer	id, name
docker.container_action_result	Result of a stop/kill/start/restart/pause/unpause command	id, name, action, success

---

Telegram Notifications and Commands

• 🐳 Docker Started — initial container list and count on startup
• 🆕 Containers Appeared — new containers detected
• 👻 Containers Disappeared — containers no longer visible to the tracker
• 🔄 Container Status Changed — previous and current status for a container
• 🏥 Container Health Changed — previous and current health state for a container
• 💥 Container OOM Killed — a container was terminated by the out-of-memory killer
• ✅ / ❌ Container Action Result — success or failure of a command (stop, kill, start, restart, pause, unpause) When --allow-docker-commands is enabled, the Telegram bot also supports container commands. Authentication is always required for these commands, even via Telegram.