nano-whale 0.1.14

A lightweight Terminal User Interface (TUI) for managing Docker containers, images, and volumes via WSL2

🐳 Nano Whale - Lightweight Docker TUI

A blazingly fast, lightweight Terminal User Interface (TUI) for managing Docker containers, images, and volumes. Built with Textual, Nano Whale provides an elegant, keyboard-driven interface for Docker management without the overhead of Docker Desktop.

📸 Screenshots

Main Interface

Container Details Panel

Environment Variables View

Port Mappings

Multi-Select Operations

Logs in Terminal

---

✨ Features

🖥️ Split-Pane Interface

• Left Pane: Three stacked tables showing Containers, Images, and Volumes simultaneously
• Right Pane: Detailed view with 5 tabbed panels for container inspection
• Bottom Panel: Real-time log output and status messages

📦 Container Management

• Start, stop, and restart containers
• View container logs (in-shell or new terminal window)
• Launch interactive terminal sessions (exec into containers)
• Delete containers with safety checks (stops running containers first)

🖼️ Image Management

• View all Docker images with size and creation info
• Delete unused images
• Multi-select for batch deletion

💾 Volume Management

• List all Docker volumes
• Delete volumes (with force option)
• Batch operations support

🔍 Container Inspection (Right Pane Tabs)

Tab	Content
Info (1)	Container ID, Image, Status, PID, Exit Code, Platform, Hostname, Restart Policy
Env (2)	All environment variables
Ports (3)	Port mappings (host → container)
Volumes (4)	Volume mounts with source, destination, and mode
Networks (5)	Network configuration, IP addresses, gateways, MAC addresses

⚡ Additional Features

• 🚀 Lightning Fast - Minimal resource footprint
• ⌨️ Keyboard-Driven - Full keyboard navigation
• 🖱️ Mouse Support - Click anywhere on a table section to switch
• 📦 Multi-Select - Batch operations on multiple items
• 🔄 Auto-Refresh - Manual refresh with A key
• 🧹 Smart Prune - Two-step confirmation for system cleanup
• 🎨 Visual Feedback - Highlighted labels show active table
• 🌐 Cross-Platform - Windows (WSL), Linux, macOS support

---

📋 Prerequisites

• Python 3.8+
• Docker Engine installed and running
• For Windows: WSL2 with Docker (or Docker Desktop)

Platform Support

Platform	Docker Command
Windows (WSL2)	wsl docker ...
Linux	docker ...
macOS	docker ...

---

📦 Installation

Via pip (Recommended)

pip install nano-whale

Via pipx (Isolated)

pipx install nano-whale

From Source

git clone https://github.com/yourusername/nano-whale.git
cd nano-whale
pip install -e .

---

🚀 Usage

Simply run:

nano-whale

Or run directly:

python main.py

---

⌨️ Keyboard Shortcuts

Table Navigation

Key	Action
C	Switch to Containers table
I	Switch to Images table
V	Switch to Volumes table
↑/↓	Navigate rows
Page Up/Down	Fast scroll
Home/End	Jump to first/last row
Mouse Click	Click anywhere on table section to switch

Detail Panel Tabs

Key	Action
1	Info tab - Container details
2	Env tab - Environment variables
3	Ports tab - Port mappings
4	Volumes tab - Volume mounts
5	Networks tab - Network configuration

Container Operations

Key	Action
S	Start container(s)
X	Stop container(s)
R	Restart container(s)
D	Delete selected item(s)

Logs & Terminal

Key	Action
L	View Logs in-shell (suspends TUI)
Ctrl+L	View Logs in new terminal window
T	Launch Terminal in-shell (exec)
Ctrl+T	Launch Terminal in new window

Multi-Select & Batch Operations

Key	Action
M	Mark/Unmark current item
(then) S/X/R/D	Perform action on all marked items

Utilities

Key	Action
A	Refresh all tables
G	Toggle Stats display in container list
P	Prune menu (press twice to confirm)
Q	Quit application

---

🎨 Interface Layout

---

📖 Usage Examples

Viewing Container Details

1. Launch Nano Whale: nano-whale
2. First container is automatically selected and details shown
3. Press 1-5 to switch between Info, Env, Ports, Volumes, Networks tabs
4. Use ↑/↓ to select different containers

Starting Multiple Containers

1. Press C to ensure Containers table is focused
2. Press M on first container to mark it [*]
3. Press ↓ then M to mark more containers
4. Press S to start all marked containers

Viewing Live Logs

In-Shell (suspends TUI):

1. Select a running container
2. Press L
3. Logs stream in terminal
4. Press Ctrl+C to return to TUI

In New Window:

1. Select a running container
2. Press Ctrl+L
3. New terminal window opens with streaming logs
4. TUI remains active

Exec into Container

In-Shell:

1. Select a running container
2. Press T
3. Interactive shell opens
4. Type exit to return to TUI

In New Window:

1. Select a running container
2. Press Ctrl+T
3. New terminal with shell opens

Cleaning Up System

1. Press P - shows warning notification
2. Press P again within 5 seconds to confirm
3. Executes docker system prune -a -f
4. Removes all unused containers, images, and volumes

Switching Between Tables

Keyboard:

• C → Containers
• I → Images
• V → Volumes

Mouse:

• Click anywhere within a table's yellow border area

---

🏗️ Architecture

┌─────────────────────────────────────┐
│         Nano Whale (Textual)        │
│              Python TUI             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Platform Detection Layer       │
│  (Windows WSL / Linux / macOS)      │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│         Docker CLI Commands         │
│   wsl docker ... (Windows WSL)      │
│   docker ... (Linux/macOS)          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│          Docker Engine              │
│    Containers │ Images │ Volumes    │
└─────────────────────────────────────┘

Key Benefits:

• ✅ No Docker Desktop required (on Windows with WSL2)
• ✅ Direct Docker Engine access
• ✅ Minimal overhead
• ✅ Works over SSH

---

🔧 Configuration

Nano Whale auto-detects your platform:

Platform	Detection	Command Prefix
Windows + WSL	wsl available	wsl docker
Windows (native)	No WSL	docker
Linux	platform.system()	docker
macOS	platform.system()	docker

---

🐛 Troubleshooting

"wsl command not found" (Windows)

wsl --install
# Restart computer after installation

"Cannot connect to Docker daemon"

Linux/macOS:

sudo systemctl start docker
# or
sudo service docker start

Windows WSL:

wsl sudo service docker start

"Permission denied"

sudo usermod -aG docker $USER
# Then log out and back in

Terminal commands not opening new windows

Nano Whale tries multiple terminal emulators:

• Windows: Windows Terminal (wt.exe), cmd.exe
• Linux: gnome-terminal, konsole, xfce4-terminal, xterm
• macOS: Terminal.app, iTerm2

Ensure at least one is installed and accessible in PATH.

---

🤝 Contributing

Contributions welcome!

# Clone
git clone https://github.com/yourusername/nano-whale.git
cd nano-whale

# Setup
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

# Run
python main.py

---

📜 License

MIT License - see LICENSE file.

---

🙏 Acknowledgments

• Built with Textual by Textualize.io
• Inspired by lazydocker and the need for a lightweight alternative

---

⭐ Star History

If you find Nano Whale useful, please give it a star on GitHub!

---

Made with ❤️ by Vriddhachalam S

Swim fast, stay light! 🐳