termainer 0.4.0

Container observability and operations directly from your terminal

Alan Stefanov

Engineering Manager · Developer Experience · Platform Engineering · FinOps · Cloud Architecture

Building scalable platforms, leading teams, and optimizing cloud operations.

---

---

Termainer

Container observability and operations directly from your terminal.

Everything you need to know about all your containers, in a single terminal.

---

Features

📊 Live Stats	Real-time CPU, memory, and network I/O with sparkline charts
📜 Log Streaming	Live logs with pause/resume, scroll support, and syntax highlighting
🔍 Full Inspection	Environment variables, networks, volumes, ports, and configuration
🔌 Multi-Provider	Supports Docker, Docker Swarm, Podman, Kubernetes, and OpenShift
📤 Report Export	Save logs with metadata for debugging and bug reporting
🌐 Remote SSH Connection	Connect to remote servers (EC2, VPS, etc.) running Docker or K8s
🖥️ Multi-Server	Monitor multiple remote and local servers simultaneously
⚡ Modern TUI	Built with Textual and Rich — fast, responsive, and terminal-native
🔄 Container Lifecycle	Start, stop, restart, and remove containers (Docker/Podman)

---

Installation

From PyPI (recommended)

pip install termainer

From Docker (ghcr.io — recommended)

docker run -it -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/alanstefanov/termainer:latest

From Docker Hub (optional)

docker run -it -v /var/run/docker.sock:/var/run/docker.sock \
  alanstefanov/termainer:latest

From source with install.sh

git clone https://github.com/AlanStefanov/termainer.git
cd termainer
chmod +x install.sh
./install.sh

Make sure ~/.local/bin is in your PATH:

export PATH="$PATH:$HOME/.local/bin"
termainer

Manual

git clone https://github.com/AlanStefanov/termainer.git
cd termainer
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .
termainer

Homebrew (coming soon)

# Once available in the official tap:
brew install termainer

In the meantime you can install manually from the community tap.

---

Updating

Depending on how you installed Termainer:

Method	Command
pip	pip install --upgrade termainer
Docker (ghcr.io)	docker pull ghcr.io/alanstefanov/termainer:latest
Docker Hub	docker pull alanstefanov/termainer:latest
install.sh	cd termainer && git pull && ./install.sh

---

Configuration

Termainer uses a YAML config file to manage multiple servers. Create ~/.config/termainer/config.yaml:

lang: en

servers:
  - label: "Local Docker"
    provider: docker
    # No host needed for local Docker

  - label: "Production Web"
    host: ec2-54-123-45-67.us-east-1.compute.amazonaws.com
    user: ubuntu
    key: ~/.ssh/production.pem
    provider: docker

  - label: "Staging K8s"
    host: k8s-staging.example.com
    user: admin
    key: ~/.ssh/staging-key
    provider: kubernetes

See the full Configuration Reference for all options.

Quick single-server (.env)

For a single remote server, you can use .env or CLI flags instead:

termainer --host ec2-54-123-45-67.us-east-1.compute.amazonaws.com \
          --ssh-user ubuntu \
          --ssh-key ~/.ssh/production.pem \
          --provider docker

---

Usage

Display Tips (Low Resolution)

If your terminal has low vertical space (for example 1366x768), reduce terminal zoom one or two steps before launching Termainer. In most terminals this is Control + Minus.

Termainer also has responsive modes, but zooming out slightly improves readability and avoids panel clipping.

Local

# Auto-detect provider
termainer

# Specific provider
termainer --provider docker
termainer --provider swarm
termainer --provider podman
termainer --provider kubernetes
termainer --provider openshift

Remote (SSH)

Connect to remote servers running Docker or Kubernetes:

# Using CLI flags
termainer --host ec2-54-123-45-67.us-east-1.compute.amazonaws.com \
          --ssh-user ubuntu \
          --ssh-key ~/.ssh/production.pem \
          --provider docker

# Using .env (recommended for frequent use)
cp .env.example .env
# Edit .env with your server details
termainer

SSH Config Auto-Discovery (Recommended)

Termainer automatically discovers servers from your ~/.ssh/config file. This is the recommended approach for multi-server setups—no .env file needed!

Simply define your remote servers in ~/.ssh/config:

Host prod-web
    HostName ec2-54-123-45-67.us-east-1.compute.amazonaws.com
    User ubuntu
    IdentityFile ~/.ssh/production.pem

Host staging-k8s
    HostName k8s-staging.example.com
    User admin
    IdentityFile ~/.ssh/staging-key

Host dev-local
    HostName 192.168.1.100
    User devuser
    IdentityFile ~/.ssh/dev-key

Then launch Termainer:

termainer

You'll see all servers from your SSH config automatically loaded in the server dropdown. No configuration files needed!

⚠️ Important: Remote servers must have the Docker CLI installed and the Docker daemon socket accessible without sudo. The user connecting via SSH must be a member of the docker group (or equivalent) so that docker ps, docker inspect, etc. work without privilege escalation. Termainer uses SSH port forwarding to tunnel the remote Docker socket to a local Unix socket, so all Docker commands run locally against the forwarded socket — this avoids issues with remote Docker versions, PATH, and --format compatibility.

SSH Authentication Methods

Method	How to use
Key (.pem)	--ssh-key ~/.ssh/key.pem or TERMAINER_REMOTE_KEY_PATH in .env
Password	--ssh-password 'mypass' or TERMAINER_REMOTE_PASSWORD in .env (requires sshpass)

For password-based auth, install sshpass:

# Debian/Ubuntu
sudo apt install sshpass

# RHEL/CentOS/Fedora
sudo yum install sshpass

Multi-Server Dashboard

The environment screen is technology-first (Docker, Swarm, Kubernetes, Podman, OpenShift).

When you configure multiple servers (via config.yaml or ~/.ssh/config), each technology dashboard can aggregate its related servers. You can:

• Server dropdown at the top of the dashboard to select a specific server
• "Todos" (All) option to see resources from all servers for that technology
• Switch servers anytime using the server dropdown in the sidebar
• Each container shows its server name prefix when in multi-server mode

The sidebar dropdown automatically populates with:

• Local (your machine)
• SSH servers from ~/.ssh/config
• Servers from config.yaml (if configured)

Keyboard Shortcuts

Technology selection screen

Key	Action
← / ↑ / ↓ / →	Navigate technologies
Enter	Open technology dashboard
q	Quit

Container dashboard

| Key | Action | |---|---|---| | ↑ / ↓ | Navigate container list | | Enter | Select container | | F5 | Refresh list | | p | Pause/resume logs | | e | Export logs | | a | Start container | | t | Stop container | | r | Restart container | | o | Restart policy | | c | Exec command | | Delete | Remove container | | Escape | Back to technology selection | | q | Quit |

---

Supported Providers

| Provider | List | Inspect | Stats | Logs | Env Vars | Start/Stop/Restart | Remove | |---|---|---|---|---|---|---|---|---| |---|---|---|---|---|---|---|---| | Docker | ✅ | ✅ | ✅ (stream) | ✅ (follow) | ✅ | ✅ | ✅ | | Docker Swarm | ✅ (services) | ✅ | ⚠️ basic | ✅ (service logs) | ✅ | ✅ (scale/update) | ✅ | | Podman | ✅ | ✅ | ✅ (poll) | ✅ (follow) | ✅ | ✅ | ✅ | | Kubernetes | ✅ | ✅ | ✅ (top) | ✅ (follow) | ✅ | ❌ | ✅ | | OpenShift | ✅ | ✅ | ✅ (top) | ✅ (follow) | ✅ | ❌ | ✅ |

All providers work both locally and remotely via SSH.

---

Architecture

CLI (termainer)
  └── app.py              ← CLI args, .env loading, SSH conn
        ├── config_manager.py ← YAML config parser (multi-server)
        ├── server_manager.py ← Multi-server connection manager
        ├── remote/           ← Remote connection module
        │   └── ssh.py        ←   SSH via subprocess (key + password)
        ├── config.py         ← .env parser and SSH builder
        ├── providers/        ← Multi-provider abstraction layer
        │   ├── base.py       ←   Abstract Protocol
        │   ├── docker.py     ←   Docker CLI (local + remote)
        │   ├── swarm.py      ←   Docker Swarm services (local + remote)
        │   ├── podman.py     ←   Podman CLI (local + remote)
        │   ├── kubernetes.py ←   kubectl (local + remote)
        │   └── openshift.py  ←   oc (extends K8s)
        ├── ui/               ← TUI layer (Textual)
        │   ├── splash.py     ←   Welcome screen
        │   ├── dashboard.py  ←   Main dashboard
        │   ├── widgets.py    ←   Reusable widgets
        │   └── styles.tcss   ←   Stylesheet
        └── utils/
            └── helpers.py    ← Utilities

---

Tech Stack

Component	Technology
Language	Python 3.10+
UI Framework	Textual
Rendering	Rich
Configuration	YAML (via PyYAML)
Providers	Docker CLI, Docker Swarm, Podman CLI, kubectl, oc
Remote Access	SSH via subprocess (key + sshpass)
Async	asyncio
Testing	pytest, pytest-asyncio
Linting	Ruff

---

Documentation

• Configuration Reference
• Configuration Reference (ES)

---

License

MIT — Alan Emanuel Stefanov

---

⭐ If you like this project, give it a star on GitHub — it helps others discover it!
github.com/AlanStefanov/termainer