{"id":46463817,"url":"https://github.com/eviltik/docker-tui","last_synced_at":"2026-03-06T04:03:48.274Z","repository":{"id":322482728,"uuid":"1089399533","full_name":"eviltik/docker-tui","owner":"eviltik","description":"A Text User Interface (TUI) for managing Docker containers and view realtime logs, embed a MCP Server for Claude Code","archived":false,"fork":false,"pushed_at":"2025-11-29T07:40:59.000Z","size":2340,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-01T08:49:09.928Z","etag":null,"topics":["claude-code","cli","devops-tools","docker","docker-logs","mcp-server","terminal-based"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eviltik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T09:41:17.000Z","updated_at":"2025-11-29T07:40:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eviltik/docker-tui","commit_stats":null,"previous_names":["eviltik/docker-tui"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/eviltik/docker-tui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eviltik%2Fdocker-tui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eviltik%2Fdocker-tui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eviltik%2Fdocker-tui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eviltik%2Fdocker-tui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eviltik","download_url":"https://codeload.github.com/eviltik/docker-tui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eviltik%2Fdocker-tui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30161345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"online","status_checked_at":"2026-03-06T02:00:08.268Z","response_time":250,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cli","devops-tools","docker","docker-logs","mcp-server","terminal-based"],"created_at":"2026-03-06T04:02:43.360Z","updated_at":"2026-03-06T04:03:48.264Z","avatar_url":"https://github.com/eviltik.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker TUI\n\nA modern, fast Terminal User Interface (TUI) for managing Docker containers, built with Go and Bubbletea.\n\n![Docker TUI](https://img.shields.io/badge/Docker-TUI-blue)\n![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go)\n![MCP Server](https://img.shields.io/badge/MCP-Server-orange)\n![License](https://img.shields.io/badge/License-MIT-green)\n\n## Features\n\n- 🐳 Container management (start/stop/restart/pause/remove)\n- 📋 Real-time log streaming with regex filtering\n- 📊 CPU monitoring per container\n- 🖱️ Mouse and keyboard support\n- 🤖 MCP server for Claude Desktop integration\n- 💾 Single binary, no dependencies\n\n![Demo](demo.gif)\n\n## Installation\n\n### Via go install\n\n```bash\ngo install github.com/eviltik/docker-tui@latest\n```\n\n### From GitHub Releases\n\nDownload pre-built binaries from the [releases page](https://github.com/eviltik/docker-tui/releases):\n\n```bash\n# Linux (amd64)\ncurl -L https://github.com/eviltik/docker-tui/releases/latest/download/docker-tui-linux-amd64.tar.gz | tar xz\nsudo mv docker-tui /usr/local/bin/\n\n# macOS (Apple Silicon)\ncurl -L https://github.com/eviltik/docker-tui/releases/latest/download/docker-tui-darwin-arm64.tar.gz | tar xz\nsudo mv docker-tui /usr/local/bin/\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/eviltik/docker-tui.git\ncd docker-tui\n\n# Build the binary\nmake build\n\n# Install system-wide (optional)\nsudo make install\n```\n\n## Usage\n\nSimply run the binary:\n\n```bash\n./docker-tui\n```\n\nOr if installed system-wide:\n\n```bash\ndocker-tui\n```\n\n### Command Line Options\n\n```bash\ndocker-tui [OPTIONS]\n```\n\nOptions:\n- `--demo` - Hide container name prefixes (removes text up to first underscore) - useful for presentations\n- `--debug-monitor` - Show debug metrics (goroutines, file descriptors, memory, active streams)\n- `--logs-buffer-length SIZE` - Maximum log lines in buffer (default: 10000, minimum: 100)\n- `--mcp-server` - Enable MCP HTTP server alongside TUI (default port: 9876)\n- `--mcp-port PORT` - Set MCP server port (default: 9876)\n- `--help`, `-h` - Show help message with all options and keyboard shortcuts\n\nExamples:\n```bash\ndocker-tui                                    # Run in normal mode\ndocker-tui --demo                             # Run in demo mode (clean container names)\ndocker-tui --debug-monitor                    # Run with debug metrics displayed\ndocker-tui --logs-buffer-length 50000         # Use 50k lines buffer for logs\ndocker-tui --mcp-server                       # Run with MCP server on port 9876\ndocker-tui --mcp-server --mcp-port 9000       # Run with MCP server on custom port\ndocker-tui --help                             # Show help\n```\n\n### Keyboard Shortcuts\n\n#### Container List View\n\n| Key | Action |\n|-----|--------|\n| `↑/↓` | Navigate up/down |\n| `PgUp/PgDown` | Jump by 10 items |\n| `Home/End` | Jump to first/last |\n| `SPACE` | Toggle selection |\n| `Shift+↑/↓` | Range selection |\n| `A` | Select all containers |\n| `Ctrl+A` | Select all running containers |\n| `X` | Clear selection |\n| `I` | Invert selection |\n| `ENTER` or `L` | Show logs for selected container(s) |\n| `S` | Start selected container(s) |\n| `K` | Kill (stop) selected container(s) |\n| `R` | Restart selected container(s) |\n| `P` | Pause/Unpause selected container(s) |\n| `D` | Remove selected container(s) |\n| `/` | Filter containers (regex support) |\n| `M` | Show MCP server logs (when `--mcp-server` is active) |\n| `Q/ESC` | Quit (with confirmation) or clear filter |\n| `Ctrl+C` | Quit immediately |\n\n#### Log View\n\n| Key | Action |\n|-----|--------|\n| `↑/↓` | Scroll logs line by line |\n| `PgUp/PgDown` | Page up/down |\n| `Home/End` | Jump to top/bottom |\n| `ENTER` | Insert timestamp mark |\n| `C` | Toggle colored backgrounds on/off |\n| `/` | Filter logs (substring search) |\n| `Q/ESC` | Return to container list or clear filter |\n\n#### Confirmation Dialog\n\n| Key | Action |\n|-----|--------|\n| `Y` | Confirm action |\n| `N` or `Q/ESC` | Cancel |\n\n### Mouse Support\n\n| Action | Effect |\n|--------|--------|\n| **Left Click** | Move cursor and toggle selection |\n| **Double Click** | Show logs for clicked container |\n| **Mouse Wheel Up/Down** | Scroll through container list |\n\n## Features in Detail\n\n### Multi-Container Selection\n\n- Use `SPACE` to toggle individual containers\n- Use `Shift+↑/↓` for range selection\n- Click with mouse to select containers\n- Selected containers are marked with a yellow `✓`\n- Actions apply to all selected containers\n\n### Mouse Interaction\n\n- **Single Click**: Move cursor to container and toggle selection\n- **Double Click**: Instantly show logs for the clicked container\n- **Mouse Wheel**: Scroll up/down through the container list\n- Works seamlessly alongside keyboard shortcuts\n\n### Log Streaming\n\n- View logs from multiple containers simultaneously\n- Each log line shows container name with colored background for easy identification\n- Toggle colored backgrounds on/off with `C` key (useful for copying logs)\n- Container names are aligned for better readability\n- Logs auto-scroll if you're at the bottom\n- Press `ENTER` to insert a timestamp mark\n- Automatic reconnection if container restarts\n- Real-time filtering with substring search (`/` key)\n\n### Filtering\n\n**Container List Filtering:**\n- Press `/` to enter filter mode\n- Supports regex patterns (case-insensitive)\n- Invalid regex patterns are highlighted in red\n- Press `ENTER` to apply filter or `ESC` to cancel\n- Filter is shown in the title bar with a 🔍 icon\n- Hidden container count is displayed in stats\n\n**Log Filtering:**\n- Press `/` to enter filter mode\n- Uses case-insensitive substring search\n- Filtering happens in real-time as you type\n- Filter applies to log content (ANSI codes are stripped for accurate matching)\n- Press `Q` or `ESC` to clear filter\n\n### Container Actions\n\nAll actions support both single and multi-container operations:\n\n- **Start**: Start stopped containers\n- **Stop**: Gracefully stop running containers (10s timeout)\n- **Restart**: Restart containers (10s timeout)\n- **Pause/Unpause**: Smart toggle - pauses running containers, unpauses paused ones\n- **Remove**: Force remove containers (with confirmation)\n\nMulti-container operations (\u003e1 selected) show a confirmation dialog with the list of affected containers.\n\n### Crash Logging\n\nAll panics are automatically captured and logged to `/tmp/docker-tui-crash.log` with:\n- Full stack traces for the crashing goroutine and all other goroutines\n- System metrics (goroutines, file descriptors, memory, GC stats)\n- Goroutine name identification for easier debugging\n- Timestamp and error details\n\nIf Docker TUI crashes, check the crash log for detailed diagnostics:\n\n```bash\ncat /tmp/docker-tui-crash.log\n```\n\n### Configurable Log Buffer\n\nCustomize the log buffer size with `--logs-buffer-length`:\n\n```bash\ndocker-tui --logs-buffer-length 50000  # 50k lines buffer\ndocker-tui --logs-buffer-length 1000   # 1k lines buffer (low memory)\n```\n\nDefault: 10,000 lines. Minimum: 100 lines.\n\nLarger buffers allow viewing more historical logs but consume more memory. Adjust based on your needs and available resources.\n\n## MCP Server (Model Context Protocol)\n\nDocker TUI includes a built-in MCP HTTP server that exposes Docker container management capabilities to AI assistants like Claude Code. The server runs alongside the TUI (or in HTTP-only mode without TTY) and provides programmatic access to container operations and logs.\n\n### Features\n\n- **HTTP Transport**: JSON-RPC 2.0 over HTTP with Server-Sent Events (SSE) support\n- **Stateless Mode**: Each request is independent, no session management required\n- **6 Powerful Tools**: Complete container lifecycle management\n- **Real-time Log Streaming**: Shared LogBroker architecture for efficient log access\n- **Auto-refresh**: Container list updates every 5 seconds\n- **CORS Enabled**: Works with web-based AI assistants\n- **High Performance**: CPU stats cached for instant responses (~6ms for list_containers)\n\n### Available Tools\n\n1. **list_containers** - List all Docker containers with status and resource usage\n   - Filter by state (running/stopped/all)\n   - Filter by name (case-insensitive substring)\n   - Returns: container ID, name, state, status, CPU%, log rate, ports\n\n2. **get_logs** - Search and fetch container logs with advanced filtering\n   - **Global search**: Leave 'containers' empty to search across ALL containers\n   - Support for regex or substring filtering (keywords like \"error\", \"warn\")\n   - Configurable line limit (default: 100, max: 10000)\n   - Automatic ANSI code stripping for accurate filtering\n   - Returns: formatted logs with container name prefix\n\n3. **get_stats** - Get detailed resource statistics\n   - Real-time CPU usage percentage\n   - Optional 10-value CPU history\n   - Log rate (lines/second)\n   - Current status and ports\n\n4. **start_container** - Start stopped containers\n   - Supports partial name matching\n   - Batch operations on multiple containers\n   - Returns: success/failure status per container\n\n5. **stop_container** - Stop running containers\n   - 10-second graceful timeout\n   - Batch operations support\n   - Returns: success/failure status per container\n\n6. **restart_container** - Restart containers\n   - 10-second timeout\n   - Works on any container state\n   - Returns: success/failure status per container\n\n### Installation with Claude Code\n\n#### Method 1: Command Line (Recommended)\n\n```bash\n# Start the MCP server\ndocker-tui --mcp-server --mcp-port 9876 \u0026\n\n# Add to Claude Code\nclaude mcp add-json docker-tui '{\n  \"type\": \"http\",\n  \"url\": \"http://localhost:9876/mcp\"\n}'\n```\n\n#### Method 2: Configuration File\n\nAdd to your `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"docker-tui\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:9876/mcp\"\n    }\n  }\n}\n```\n\nThen start the server:\n\n```bash\ndocker-tui --mcp-server --mcp-port 9876\n```\n\n#### Method 3: Project-level Configuration\n\nCreate `.mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"docker-tui\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:9876/mcp\"\n    }\n  }\n}\n```\n\n### Testing the MCP Server\n\nOnce installed, you can test each tool with Claude Code. Here are example prompts:\n\n#### 1. List Containers\n\n```\nShow me all my running Docker containers\n```\n\n```\nList all containers including stopped ones\n```\n\n```\nFind containers with \"nginx\" in their name\n```\n\n#### 2. Get Logs\n\n```\nShow me the last 50 lines of logs from my nginx container\n```\n\n```\nGet logs from redis container and filter for errors\n```\n\n```\nShow me logs from all containers matching \"api\" with lines containing \"WARNING\"\n```\n\n```\nGet the last 10 lines from mongodb container using regex filter for \"connection.*failed\"\n```\n\n#### 3. Get Statistics\n\n```\nWhat's the CPU usage of my running containers?\n```\n\n```\nShow me detailed stats with CPU history for the postgres container\n```\n\n```\nGet resource usage for all containers matching \"web\"\n```\n\n#### 4. Start Containers\n\n```\nStart the nginx container\n```\n\n```\nStart all containers with \"test\" in their name\n```\n\n#### 5. Stop Containers\n\n```\nStop the redis container gracefully\n```\n\n```\nStop all containers matching \"dev\"\n```\n\n#### 6. Restart Containers\n\n```\nRestart the mongodb container\n```\n\n```\nRestart all api containers\n```\n\n#### Advanced Multi-Tool Workflows\n\n```\nList all running containers, then show me logs from the one using the most CPU\n```\n\n```\nFind containers with \"staging\" in the name, get their stats, and restart any that are using more than 80% CPU\n```\n\n```\nShow me all stopped containers, then start the ones that contain \"service\" in their name\n```\n\n### HTTP-Only Mode\n\nWhen running in an environment without a TTY (like Docker or systemd), the server automatically runs in HTTP-only mode:\n\n```bash\n# In a Docker container or background service\ndocker-tui --mcp-server --mcp-port 9876\n# Output: Running in HTTP-only mode (no TTY detected)\n```\n\n### Architecture\n\n- **Transport**: StreamableHTTPServerTransport from [go-mcp](https://github.com/ThinkInAIXYZ/go-mcp)\n- **Protocol**: JSON-RPC 2.0 with SSE support\n- **Log Streaming**: Shared LogBroker instance with the TUI\n- **CPU Stats Cache**: Shared cache updated every 5 seconds for instant MCP responses\n- **Auto-discovery**: Container list refreshes every 5 seconds\n- **Graceful Shutdown**: Proper cleanup on SIGINT/SIGTERM\n\n## Development\n\n### Prerequisites\n\n- Go 1.24 or higher\n- Docker installed and running\n- Access to Docker socket (`/var/run/docker.sock`)\n\n### Building\n\n```bash\n# Build for current platform\nmake build\n\n# Run without building\nmake run\n\n# Build for all platforms\nmake dist-all\n\n# Clean build artifacts\nmake clean\n\n# Run tests\nmake test\n\n# Format code\nmake fmt\n```\n\n## Troubleshooting\n\n### Permission Denied\n\nIf you get \"permission denied\" accessing Docker socket:\n\n```bash\n# Add your user to docker group\nsudo usermod -aG docker $USER\n\n# Or run with sudo (not recommended)\nsudo ./docker-tui\n```\n\n### Docker Not Running\n\nMake sure Docker daemon is running:\n\n```bash\n# Check Docker status\nsystemctl status docker\n\n# Start Docker\nsudo systemctl start docker\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request or suggest improvement by opening a ticket.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Author\n\neviltik\n\n## Acknowledgments\n\n- [Bubbletea](https://github.com/charmbracelet/bubbletea) - Excellent TUI framework\n- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Beautiful terminal styling\n- [Docker](https://www.docker.com/) - Container platform\n- [Claude Code](https://claude.com/claude-code) - AI-powered development assistance\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feviltik%2Fdocker-tui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feviltik%2Fdocker-tui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feviltik%2Fdocker-tui/lists"}