nano-whale 0.1.1

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 via WSL2. Built with Textual, Nano Whale provides an elegant, keyboard-driven interface for Docker management without the overhead of Docker Desktop.

✨ Features

• 🚀 Lightning Fast - Minimal resource footprint, native WSL2 integration
• ⌨️ Keyboard-Driven - Navigate and manage Docker resources without touching your mouse
• 📦 Multi-Select Operations - Perform batch operations on multiple containers/images/volumes
• 📊 Real-Time Monitoring - Live container status updates and log streaming
• 🎨 Beautiful TUI - Clean, intuitive interface built with Textual
• 🔄 Quick Switching - Toggle between containers, images, and volumes instantly
• 🧹 Smart Cleanup - Built-in prune commands for system maintenance
• 🪶 Ultra-Lightweight - Zero dependencies except Textual and WSL2

🎯 Why Nano Whale?

Tired of Docker Desktop's resource consumption? Nano Whale gives you:

• No GUI Overhead - Terminal-based means minimal memory usage
• WSL2 Native - Direct integration with Docker Engine in WSL2
• Keyboard Efficiency - Faster than clicking through GUI menus
• SSH-Friendly - Works perfectly over SSH connections
• Open Source - Free and community-driven

📋 Prerequisites

• Windows 10/11 with WSL2 installed
• Docker Engine running in WSL2 (not Docker Desktop)
• Python 3.8+

Quick WSL2 & Docker Setup

If you don't have WSL2 and Docker Engine set up:

# Install WSL2
wsl --install

# After restart, install Docker in WSL
wsl
sudo apt update
sudo apt install docker.io -y
sudo service docker start

📦 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/docker_clui
pip install -e .

🚀 Usage

Simply run the command:

nano-whale

⌨️ Keyboard Shortcuts

Navigation & Modes

Key	Action
C	Switch to Containers view
I	Switch to Images view
V	Switch to Volumes view
A	Refresh current view
↑/↓	Navigate through list

Container Operations

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

Multi-Select

Key	Action
M	Mark/Unmark current item for batch operations
M (multiple)	Select multiple items, then perform action

Cleanup & Maintenance

Key	Action
P	Open Prune menu (containers/images/volumes)
P (twice)	Confirm and execute full system prune

General

Key	Action
Q	Quit application

📖 Usage Examples

Starting Multiple Containers

1. Press C to enter Containers view
2. Press M on first container to mark it
3. Press ↓ to move to next container
4. Press M to mark second container
5. Press S to start all marked containers

Viewing Container Logs

1. Navigate to desired container with ↑/↓
2. Press L to stream logs
3. Logs appear in the bottom panel
4. Navigate away to stop streaming

Cleaning Up Unused Images

1. Press I to switch to Images view
2. Press P to open prune menu
3. Select "Prune Unused Images"
4. Confirm deletion

Full System Cleanup

1. Press P once to prepare prune
2. Press P again within 3 seconds to confirm
3. All unused containers, images, and volumes will be removed

🎨 Interface Overview

┌─────────────────────────────────────────────────────────────┐
│ 🐳 Nano Whale - Docker TUI                                  │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  CONTAINER ID    IMAGE           STATUS      PORTS          │
│  ───────────────────────────────────────────────────────    │
│  abc123def456    nginx:latest    Up 2 hours  80->80         │
│  789ghi012jkl    postgres:15     Up 1 day    5432->5432     │
│  mno345pqr678    redis:alpine    Exited      -              │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│ Status: Container abc123def456 started successfully         │
│ Multi-select: 2 items marked                                │
└─────────────────────────────────────────────────────────────┘
 Q: Quit | A: Refresh | C: Containers | I: Images | V: Volumes

🏗️ Architecture

Nano Whale executes Docker commands through WSL2:

nano-whale (Python/Textual)
    ↓
wsl docker <command>
    ↓
Docker Engine (WSL2)
    ↓
Your Containers/Images/Volumes

This architecture means:

• No Docker Desktop required
• Direct engine access
• Minimal overhead
• Maximum performance

🔧 Configuration

Nano Whale uses wsl docker commands by default. If your setup is different, you can modify the command prefix in the source.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

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

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Run from source
python -m docker_clui.app

🐛 Troubleshooting

"wsl command not found"

Install WSL2:

wsl --install

"Cannot connect to Docker daemon"

Start Docker in WSL:

wsl sudo service docker start

"Permission denied"

Add your user to the docker group:

wsl sudo usermod -aG docker $USER

Then restart your WSL session.

Commands not working from Windows terminal

Prefix commands with wsl:

wsl docker ps
wsl docker images

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Textual by Textualize.io
• Inspired by the need for a lightweight Docker Desktop alternative
• Thanks to the Docker and WSL2 teams for their excellent tools

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

🗺️ Roadmap

• Docker Compose support
• Container stats dashboard (CPU, Memory, Network)
• Custom color themes
• Export/Import container configurations
• Remote Docker host support
• Container shell access (exec)
• Network management
• Volume backup/restore

⭐ Star History

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

---

Made with ❤️ by Vriddhachalam S

Swim fast, stay light! 🐳