containerctl

containerctl

A lightweight terminal UI for Docker container management, built for speed over remote SSH connections

Overview

containerctl removes the friction from managing containers over SSH. It’s a lightweight CLI that lets you instantly inspect, control, and tail logs from containers — perfect for remote servers where you want speed, not tooling overhead.

It sits as a thin layer between the tview TUI framework and the Moby Docker client. It supports connecting to a remote Docker Engine API directly over SSH, so you can manage containers on a remote host without SSHing in manually.

TUI

The default view lists all containers on the connected host. Select a container with the arrow keys, then:

• Press l to stream its logs in real time.
• Press t to open an interactive shell session inside the container. This is also the preferred way to explore a running container's filesystem. Exit the shell as usual with exit.
• Press f to browse the filesystem without a shell — useful for stopped containers or distroless images that have no shell. The view reads only the tar headers of the container's filesystem, so no data is extracted. Navigate into directories with Enter or use .. to go up.
• Press s / x to start or stop a container, or p / u to pause or unpause it.

Press Esc from any sub-view to return to the container list, or q to quit.

SSH

When --host is provided, containerctl connects to the remote Docker Engine API over SSH, tunneling all API calls through the connection. No manual SSH session is needed.

The SSH behavior is designed to mirror OpenSSH: ~/.ssh/config is read and its values take precedence over command-line arguments. Host keys are verified against ~/.ssh/known_hosts. Authentication follows the same order as OpenSSH — password prompt, SSH agent (SSH_AUTH_SOCK), or a private key file, with a passphrase prompt if the key is encrypted.

Examples

  # Connect to local Docker
  containerctl

  # Connect to remote host using default SSH settings
  containerctl --host my-host

  # Connect to remote host using with SSH key
  containerctl --host my-host:23 --identity-file ~/.ssh/id_rsa

  # Connect to remote host with username embedded in host and password prompted
  containerctl --host username@my-host --ask-password true

Install

Download the binary for your platform from the releases page.

macOS (Apple Silicon)

VERSION=v0.5.1  # replace with the desired version
curl -LO https://github.com/Br0ce/containerctl/releases/download/${VERSION}/containerctl-${VERSION}-darwin-arm64

# Verify the checksum against the value published on the releases page
shasum -a 256 containerctl-${VERSION}-darwin-arm64

chmod +x containerctl-${VERSION}-darwin-arm64
sudo mv containerctl-${VERSION}-darwin-arm64 /usr/local/bin/containerctl
containerctl --version

Linux (amd64)

VERSION=v0.5.1  # replace with the desired version
curl -LO https://github.com/Br0ce/containerctl/releases/download/${VERSION}/containerctl-${VERSION}-linux-amd64

# Verify the checksum against the value published on the releases page
sha256sum containerctl-${VERSION}-linux-amd64

chmod +x containerctl-${VERSION}-linux-amd64
sudo mv containerctl-${VERSION}-linux-amd64 /usr/local/bin/containerctl
containerctl --version

Install from Source

Requirements

• Go 1.26+

git clone https://github.com/Br0ce/containerctl.git
cd containerctl
make build

The binary will be placed at ./bin/containerctl.

Usage

./bin/containerctl
# or
make run

Development

Install dependencies and tooling:

make setup

Available make targets:

Acknowledgements

• Inspired by k9s
• TUI built with tview by @rivo
• Docker integration via the Moby Go client

License

Apache 2.0 — see LICENSE.