convoy

🚢 Manage multiple containers and multiple tasks at once

Convoy is a Go-based CLI tool for orchestrating multiple Alpine Linux containers via Docker. It uses gRPC for communication, supervisord for process management, and round-robin load balancing to distribute tasks evenly.

Features

• Container Orchestration: Create, manage, and stop multiple Alpine Linux containers.
• Command Execution: Send commands to individual containers or all at once via gRPC over TCP.
• Load Balancing: Evenly distribute tasks across containers using a round-robin algorithm.
• Individual Management: Inspect, view logs, check stats (CPU/memory), restart, and access interactive shells on containers.
• Process Management: Supervisord handles gRPC servers in containers for reliability.
• CLI: Built with Cobra; alias cvy for convenience.

Installation

Prerequisites: Go 1.21+, Docker, GitHub CLI (for remote setup).

go install ./cmd/convoy

Usage

convoy --help
# or
cvy --help

Available commands

• convoy start <name> – Creates (if needed) and starts a new container registered under the provided CLI name. Running the same name again reuses the existing container instead of spawning a duplicate.
• convoy stop <name|id> – Stops and removes the container identified by name or ID. Use -a/--all to stop and remove every tracked container.
• convoy list – Lists all containers managed by Convoy along with their CLI name, image, and agent endpoint.
• convoy config - Show, validate or initialize Convoy configuration.
• convoy health - Check if Convoy is running and healthy. Use -a/--all to see the health status of every tracked container.
• convoy exec <name|id> <command> – Execute a non-interactive command inside a container via the gRPC agent.
• convoy shell <name|id> – Open an interactive shell session in a container with full PTY support.
• convoy copy <src> <dest> – Copy files to/from containers using <name>:<path> syntax.

Shell Command

The shell command provides an interactive terminal session inside a container with full PTY (pseudo-terminal) support:

# Open default shell in container
convoy shell my-container

# Run a specific shell or command
convoy shell my-container -- /bin/bash

# With environment variables and working directory
convoy shell my-container -w /app -e FOO=bar -e DEBUG=1

# With session timeout
convoy shell my-container --timeout 30m

Features:

• Full terminal emulation (colors, cursor control, line editing)
• Window resize support (automatically adjusts when you resize your terminal)
• Ctrl+C forwarding to the remote process
• Configurable session timeout

Development

This project uses just as a command runner. Install it with:

cargo install just

Available recipes

Run just or just --list to see all available recipes:

• just compile - Build the Go binary
• just test - Run all tests
• just lint - Run the linter
• just clean - Clean build artifacts
• just build-image - Build the Docker image

Image Setup

Convoy uses a custom Alpine Linux image with a pre-configured supervisor process to manage gRPC servers. To build the image, run:

just build-image

By default, the image is tagged as convoy:latest. The image currently only containers opencode and the packages to run it. However, the image being used can be changed in the configuration file.

Contributing

Contributions welcome! See LICENSE for details.