DockScope

Visual, interactive Docker infrastructure debugger.

A browser-based 3D dependency graph of your Docker services with live health, logs, metrics, and container actions. Mission control for your Docker Compose stacks.

Table of Contents

• Quick Start
• Features
• Keyboard Shortcuts
• API
• Development
• Tech Stack
• Contributing

Quick Start

Prerequisites: Node.js (v18+) and Docker must be installed and running. Kubernetes graph support is enabled automatically when DockScope can load a kubeconfig or in-cluster service account with read access to the Kubernetes API.

npx dockscope up

Or install globally:

npm install -g dockscope
dockscope up

Docker (no Node.js needed)

docker run --rm --pull always -p 4681:4681 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/manuelr-t/dockscope

Note: The Docker image does not include Compose project management (up/down/destroy) since it cannot access host compose files. All other features work normally.

Security: Mounting /var/run/docker.sock gives DockScope control over the host Docker daemon, including container actions and exec access. Only run it on trusted machines and networks.

Opens http://localhost:4681.

Option	Default	Description
-p, --port <port>	4681	Server port (auto-increments if in use)
--no-open	—	Don't open browser
dockscope scan	—	Output graph as JSON (no UI)

Features

• 3D Force Graph — Containers as interactive spheres, color-coded by health/status, with depends_on arrows and network links. Node size scales by importance (ports, connections, CPU, memory, I/O). Compose projects grouped with enclosure spheres.
• Live Monitoring — CPU, memory, network I/O polled every 3s with 5-minute sparkline history. Real-time Docker event stream.
• Anomaly Detection — CPU/memory spikes flagged using IQR-based outlier detection. Pulsing indicator on graph nodes, toast notification, and dismissable sidebar alert.
• Crash Diagnostics — When a container dies, auto-analyzes exit code, OOM status, and last log lines to surface the likely cause. Diagnostic card shown in the sidebar.
• Dependency Impact View — Select a node and toggle impact mode (I key) to highlight everything that would break if it goes down. Traverses depends_on upstream and dims unaffected nodes.
• Container Actions — Start, stop, restart, pause, unpause, kill, remove — directly from the sidebar with confirmation dialogs for destructive actions.
• Log Streaming — Live logs with ANSI color support, in-log search, and export to .txt.
• Interactive Terminal — Shell access (/bin/sh) via xterm.js embedded in the sidebar.
• Compose Manager — Up, down, stop, restart, destroy entire projects. Cached metadata survives docker compose down.
• Container Inspection — Env vars (secrets auto-masked), labels, mounts, processes, filesystem diff — all in sidebar tabs.
• Search & Filters — Real-time search by name/image, status filters (running/stopped/unhealthy), network color toggle.
• Kubernetes Graph — Pods, Services, Ingresses, and HPAs are rendered alongside Docker resources when Kubernetes API credentials are available. Services link to selected pods, Ingresses link to Services, HPAs show current vs desired replicas, and the HUD can filter Kubernetes resources by namespace.

Keyboard Shortcuts

Key	Action
/ or Ctrl+K	Focus search
Escape	Close panel / clear search
F	Zoom to fit
R	Reset camera
C	Center on selected node
I	Toggle impact view
?	Show shortcut help

API

Method	Path	Description
GET	/api/graph	Full graph (nodes + links)
GET	/api/containers/:id/stats	CPU, memory, network I/O
GET	/api/containers/:id/logs?tail=N	Logs (default 200 lines)
GET	/api/containers/:id/inspect	Env, labels, mounts, config
GET	/api/containers/:id/history	Metric sparkline data
GET	/api/containers/:id/top	Running processes
GET	/api/containers/:id/diff	Filesystem changes
GET	/api/containers/:id/diagnostic	Crash diagnostic analysis
POST	/api/containers/:id/{action}	start, stop, restart, pause, unpause, kill
DELETE	/api/containers/:id?volumes=true	Remove container
GET	/api/projects	List compose projects
POST	/api/projects/:name/{action}	up, down, stop, start, restart, destroy
GET	/api/system	Docker version, CPUs, memory
GET	/api/health	Docker connectivity check
GET	/api/version	Current + latest version
WS	/ws	Real-time graph, stats, events, logs, exec, anomalies, diagnostics

Development

git clone https://github.com/ManuelR-T/dockscope.git
cd dockscope
npm install
npm run dev    # Starts on port 4681 with Vite HMR

Command	Description
npm run dev	Dev server (backend + frontend with HMR)
npm run build	Production build
npm run start	Run production build
npm test	Run unit tests (vitest)
npm run lint	ESLint check
npm run format	Prettier format
npm run typecheck	TypeScript check

Tech Stack

Layer	Technology
Frontend	Svelte 5, Three.js, 3d-force-graph, xterm.js
Backend	Express, WebSocket (ws), dockerode
Build	Vite, TypeScript
Testing	Vitest
CLI	Commander
CI/CD	GitHub Actions, commitlint, ESLint, Prettier

Contributing

See CONTRIBUTING.md.

License

MIT