ctop

ctop

Language / Sprache: Deutsch | English

Top-like interface for container metrics / Top-artige Oberfläche für Container-Metriken

Deutsche Dokumentation

Projektübersicht

ctop ist ein Terminal-basiertes Monitoring-Tool für Container. Es zeigt Echtzeit-Metriken (CPU, Speicher, Netzwerk, I/O) für mehrere Container in einer kompakten Übersicht sowie einer Einzelansicht für detaillierte Container-Informationen.

Unterstützte Container-Runtimes: Docker und runC.

Fork-Informationen

Dies ist ein gepflegter Fork von bcicen/ctop, ursprünglich erstellt von VektorLab.

ctop ist für mich ein unverzichtbares Werkzeug im täglichen Umgang mit Containern — kompakt, schnell und auf den Punkt. Leider wird das Original-Projekt seit längerer Zeit nicht mehr aktiv weiterentwickelt. Da ich das Tool regelmäßig nutze und es nicht aufgeben möchte, pflege ich es hier als eigenständigen Fork weiter: mit aktuellen Abhängigkeiten, Security-Fixes und modernem Go.

Änderungen in diesem Fork:

• Security-Fixes (Shell-Injection, Dateiberechtigungen, Debug-Server-Binding, Secret-Redaction in Anzeige und Debug-Logs)
• Supply-Chain-Härtung (SHA-gepinnte CI-Actions, Dependabot, Digest-gepinntes Docker-Base-Image)
• Aktualisierung auf Go 1.22 mit modernen stdlib-Paketen (log/slog, os.ReadDir)
• Ersetzen nicht gepflegter Dependencies (op/go-logging, nu7hatch/gouuid, pkg/errors)
• GitHub Actions CI/CD mit Multi-Plattform-Builds (Linux amd64/arm64, macOS amd64/arm64, Windows amd64)
• Docker-Images über GHCR (ghcr.io/eqms/ctop)

Installation

Binaries herunterladen

Die neuesten Binaries gibt es auf der Releases-Seite:

# Linux (amd64)
sudo curl -Lo /usr/local/bin/ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-linux-amd64
sudo chmod +x /usr/local/bin/ctop

# macOS (Apple Silicon)
curl -Lo ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-darwin-arm64
chmod +x ctop
sudo mv ctop /usr/local/bin/

# macOS (Intel)
curl -Lo ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-darwin-amd64
chmod +x ctop
sudo mv ctop /usr/local/bin/

macOS Hinweis: Beim Download über einen Browser setzt macOS das Quarantine-Flag, wodurch Gatekeeper die Ausführung blockiert. Abhilfe:

# Quarantine-Flag entfernen
xattr -d com.apple.quarantine ./ctop-0.8.5-darwin-arm64
chmod +x ./ctop-0.8.5-darwin-arm64

Bei Installation per curl (wie oben) wird kein Quarantine-Flag gesetzt.

Homebrew (macOS & Linux)

brew install eqms/ctop/ctop

Docker

docker run --rm -ti \
  --name=ctop \
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/eqms/ctop:latest

Verwendung

ctop benötigt keine Argumente und nutzt standardmäßig die Docker-Host-Variablen. Weitere Konfigurationsoptionen unter Connectors.

Optionen

Tastenbelegung

Konfigurationsdatei

Während der Ausführung kann mit S die aktuelle Konfiguration gespeichert werden:

• XDG-Systeme: ~/.config/ctop/config
• Fallback: ~/.ctop

Bauen aus Quellcode

git clone https://github.com/eqms/ctop.git
cd ctop
make build

Alle Plattformen

make build-all    # Binaries in _build/

Docker-Image

make image        # Erstellt lokales ctop:latest Image

Architektur

ctop/
├── main.go                  # Einstiegspunkt, CLI-Flags
├── grid.go                  # Haupt-UI-Grid-Steuerung
├── cursor.go                # Grid-Cursor / Navigation
├── menus.go                 # TUI-Menüs (Container, Filter, Sortierung)
├── config/                  # Konfigurationsverwaltung (TOML)
├── connector/               # Container-Runtime-Abstraktionen
│   ├── docker.go            # Docker-Connector
│   ├── runc.go              # runC-Connector (Linux)
│   ├── mock.go              # Mock-Connector (Entwicklung)
│   ├── collector/           # Metrik-Sammler
│   └── manager/             # Container-Lifecycle-Management
├── container/               # Container-Modell und Sortierung
├── cwidgets/                # TUI-Widgets
│   ├── compact/             # Kompakte Grid-Ansicht
│   └── single/              # Einzelansicht (CPU, Mem, Net, I/O)
├── logging/                 # Logging (log/slog + Ring Buffer)
├── widgets/                 # Basis-UI-Widgets
├── Makefile                 # Build-Targets
├── Dockerfile               # Multi-Stage Docker Build
└── .github/workflows/ci.yml # GitHub Actions CI/CD

Entwicklung

Voraussetzungen: Go 1.26+

# Entwicklungsmodus mit Debug-Server
make run-dev

# Debug-Optionen (Umgebungsvariablen)
CTOP_DEBUG=1          # Debug-Logging und Unix-Socket-Server aktivieren
                      # Socket: $XDG_RUNTIME_DIR/ctop.sock bzw. $TMPDIR/ctop-<uid>/ctop.sock
CTOP_DEBUG_TCP=1      # TCP Debug-Server (127.0.0.1:9000, ohne Auth) statt Unix-Socket
CTOP_DEBUG_FILE=/path # Log-Ausgabe zusätzlich in Datei schreiben

Connectors

CI/CD

GitHub Actions Pipeline mit 4 Jobs:

1. test — go test ./...
2. build — Cross-Compile für 5 Plattformen
3. release — GitHub Release mit Binaries + SHA256 Checksums (bei Tag-Push v*)
4. docker — Multi-Arch Docker Image auf GHCR (bei Tag-Push v*)

Lizenz

MIT License — Copyright (c) 2017 VektorLab. Siehe LICENSE.

English Documentation

Project Overview

ctop is a terminal-based monitoring tool for containers. It displays real-time metrics (CPU, memory, network, I/O) for multiple containers in a compact overview as well as a single container view for detailed inspection.

Supported container runtimes: Docker and runC.

Fork Information

This is a maintained fork of bcicen/ctop, originally created by VektorLab.

ctop is an indispensable tool in my daily work with containers — compact, fast and to the point. Unfortunately, the original project is no longer actively maintained. Since I use this tool on a regular basis and don't want to let it go, I maintain it here as an independent fork: with up-to-date dependencies, security fixes and modern Go.

Changes in this fork:

• Security fixes (shell injection, file permissions, debug server binding, secret redaction in UI and debug logs)
• Supply-chain hardening (SHA-pinned CI actions, Dependabot, digest-pinned Docker base image)
• Updated to Go 1.22 with modern stdlib packages (log/slog, os.ReadDir)
• Replaced unmaintained dependencies (op/go-logging, nu7hatch/gouuid, pkg/errors)
• GitHub Actions CI/CD with multi-platform builds (Linux amd64/arm64, macOS amd64/arm64, Windows amd64)
• Docker images published to GHCR (ghcr.io/eqms/ctop)

Installation

Download Binaries

Get the latest binaries from the Releases page:

# Linux (amd64)
sudo curl -Lo /usr/local/bin/ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-linux-amd64
sudo chmod +x /usr/local/bin/ctop

# macOS (Apple Silicon)
curl -Lo ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-darwin-arm64
chmod +x ctop
sudo mv ctop /usr/local/bin/

# macOS (Intel)
curl -Lo ctop https://github.com/eqms/ctop/releases/latest/download/ctop-0.8.5-darwin-amd64
chmod +x ctop
sudo mv ctop /usr/local/bin/

macOS Note: When downloading via a browser, macOS sets the quarantine flag and Gatekeeper blocks execution. Fix:

# Remove quarantine flag
xattr -d com.apple.quarantine ./ctop-0.8.5-darwin-arm64
chmod +x ./ctop-0.8.5-darwin-arm64

When installing via curl (as shown above), no quarantine flag is set.

Homebrew (macOS & Linux)

brew install eqms/ctop/ctop

Docker

docker run --rm -ti \
  --name=ctop \
  --volume /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/eqms/ctop:latest

Usage

ctop requires no arguments and uses Docker host variables by default. See connectors for further configuration options.

Options

Keybindings

Config File

While running, press S to save the current configuration:

• XDG systems: ~/.config/ctop/config
• Fallback: ~/.ctop

Building from Source

git clone https://github.com/eqms/ctop.git
cd ctop
make build

All Platforms

make build-all    # Binaries in _build/

Docker Image

make image        # Builds local ctop:latest image

Architecture

ctop/
├── main.go                  # Entry point, CLI flags
├── grid.go                  # Main UI grid controller
├── cursor.go                # Grid cursor / navigation
├── menus.go                 # TUI menus (container, filter, sort)
├── config/                  # Configuration management (TOML)
├── connector/               # Container runtime abstractions
│   ├── docker.go            # Docker connector
│   ├── runc.go              # runC connector (Linux only)
│   ├── mock.go              # Mock connector (development)
│   ├── collector/           # Metrics collectors
│   └── manager/             # Container lifecycle management
├── container/               # Container model and sorting
├── cwidgets/                # TUI widgets
│   ├── compact/             # Compact grid view
│   └── single/              # Single view (CPU, Mem, Net, I/O)
├── logging/                 # Logging (log/slog + ring buffer)
├── widgets/                 # Base UI widgets
├── Makefile                 # Build targets
├── Dockerfile               # Multi-stage Docker build
└── .github/workflows/ci.yml # GitHub Actions CI/CD

Development

Prerequisites: Go 1.26+

# Development mode with debug server
make run-dev

# Debug options (environment variables)
CTOP_DEBUG=1          # Enable debug logging and Unix socket server
                      # Socket: $XDG_RUNTIME_DIR/ctop.sock or $TMPDIR/ctop-<uid>/ctop.sock
CTOP_DEBUG_TCP=1      # Use TCP debug server (127.0.0.1:9000, unauthenticated) instead of Unix socket
CTOP_DEBUG_FILE=/path # Additionally write log output to file

Connectors

CI/CD

GitHub Actions pipeline with 4 jobs:

1. test — go test ./...
2. build — Cross-compile for 5 platforms
3. release — GitHub Release with binaries + SHA256 checksums (on tag push v*)
4. docker — Multi-arch Docker image to GHCR (on tag push v*)

License

MIT License — Copyright (c) 2017 VektorLab. See LICENSE.