Claude Code Podman Container Workflow Setup Tutorial

Containerization has become essential for modern development workflows, and Podman offers a daemonless, rootless alternative to Docker that integrates perfectly with Claude Code’s skill system. This tutorial walks you through setting up Podman container workflows using Claude Code skills, enabling you to automate container management through natural language commands.

Prerequisites and Installation

Before creating container-focused skills, ensure you have both Podman and Claude Code installed on your system.

Installing Podman

On macOS, Podman is available through Homebrew:

brew install podman
podman machine init
podman machine start

On Linux, use your distribution’s package manager:

# Fedora/RHEL
sudo dnf install podman

# Ubuntu/Debian
sudo apt-get install podman

Verify the installation:

podman --version
podman info

Verifying Claude Code

Ensure Claude Code is installed and accessible:

claude --version

Creating a Podman Management Skill

Claude Code skills allow you to封装 complex workflows into reusable commands. Let’s create a skill for Podman container management.

Skill Structure

A Claude Code skill is a Markdown file with YAML front matter. Create a file named podman-manager.skill.md:

---
name: podman-manager
description: "Manage Podman containers with Claude Code - start, stop, inspect, and monitor containers"
---

# Podman Container Manager

You help users manage Podman containers through natural language commands.

## Available Commands

- **List containers**: Run `podman ps -a --format "{{.Names}}\t{{.Status}}\t{{.Image}}"`
- **Start container**: Run `podman start <container_name_or_id>`
- **Stop container**: Run `podman stop <container_name_or_id>`
- **Inspect container**: Run `podman inspect <container_name_or_id>`
- **View logs**: Run `podman logs -f <container_name_or_id>`
- **Remove container**: Run `podman rm <container_name_or_id>`
- **List images**: Run `podman images`

When asked to manage containers, extract the container name or ID from the user's request and execute the appropriate command. Always confirm the action before executing destructive commands.

Installing the Skill

Copy the skill file to Claude Code’s skills directory:

# Find the skills directory
CLAUDE_SKILLS_DIR=~/.claude/skills
mkdir -p "$CLAUDE_SKILLS_DIR"

# Copy the skill
cp podman-manager.skill.md "$CLAUDE_SKILLS_DIR/podman-manager.md"

Automating Development Container Workflows

Beyond basic container management, you can create skills that automate complex development workflows involving containers.

Development Environment Skill

Create a skill that sets up development containers for different project types:

---
name: dev-container
description: "Create and manage development containers for various programming languages"
---

# Development Container Helper

You assist developers in creating and managing development containers.

## Workflow Patterns

### Python Development Container

Create a Python development environment:

```bash
podman run -dit --name python-dev \
  -v "$PWD:/workspace" \
  -w /workspace \
  python:3.11-slim \
  bash

Node.js Development Container

Create a Node.js development environment:

podman run -dit --name node-dev \
  -v "$PWD:/workspace" \
  -w /workspace \
  -p 3000:3000 \
  node:20-slim \
  bash

Database Development Container

Start a PostgreSQL container:

podman run -dit --name postgres-dev \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=devdb \
  -v postgres-data:/var/lib/postgresql/data \
  postgres:15

When users request a development environment, ask which language or service they need, then execute the appropriate container creation command.

### Database Container Skill

Create a skill specifically for database containers:

```yaml
---
name: db-containers
description: "Quickly start and manage database containers for development"
---

# Database Container Manager

You help users quickly spin up database containers for development and testing.

## Supported Databases

### PostgreSQL
Start: `podman run -d --name postgres-dev -e POSTGRES_PASSWORD=dev -e POSTGRES_DB=mydb postgres:15`
Connect: `podman exec -it postgres-dev psql -U postgres mydb`

### MySQL
Start: `podman run -d --name mysql-dev -e MYSQL_ROOT_PASSWORD=dev -e MYSQL_DATABASE=mydb mysql:8`
Connect: `podman exec -it mysql-dev mysql -u root -p mydb`

### Redis
Start: `podman run -d --name redis-dev -p 6379:6379 redis:7`
Connect: `podman exec -it redis-dev redis-cli`

When users need a database, suggest the appropriate container and provide connection instructions.

Advanced: Container Health Monitoring

Create a monitoring skill that tracks container health and resource usage:

---
name: container-monitor
description: "Monitor container health, resource usage, and performance metrics"
---

# Container Health Monitor

You monitor container health and provide diagnostic information.

## Monitoring Commands

### Check Container Status
```bash
podman ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

View Resource Usage

podman stats --no-stream --format "table {{.Name}}\t{{.CPU}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"

Inspect Container Health

podman inspect --format='{{.State.Health.Status}}' <container_name>

View Container Logs

podman logs --tail=50 <container_name>

When asked to check container health, run these commands and interpret the results for the user. Flag any containers that are not running or have degraded health.

## Practical Examples

Here are real-world scenarios where these skills shine:

### Example 1: Starting a New Python Project

User: “I need to start a new Python web project with Flask” Claude: Creates a Python development container, installs Flask, and sets up the project structure

The skill executes:
```bash
podman run -dit --name flask-dev -v "$PWD:/workspace" -w /workspace -p 5000:5000 python:3.11-slim
podman exec flask-dev pip install flask

Example 2: Running Tests Against Different Databases

User: "Run my integration tests with PostgreSQL 13, then with PostgreSQL 15"
Claude: Spins up both database containers, runs tests against each, and reports results

Example 3: Debugging a Container Issue

User: "My container keeps crashing, help me debug"
Claude: Inspects container logs, checks health status, reviews resource usage, and suggests fixes

Best Practices

When working with Podman and Claude Code skills:

Use rootless containers: Podman’s rootless mode doesn’t require special privileges
Volume mounting: Mount local directories for persistent development work
Clean up regularly: Remove unused containers and images to save space
Use named containers: Easier to identify than random container IDs
Health checks: Include health checks in your containers for monitoring

Conclusion

By combining Claude Code’s natural language capabilities with Podman’s flexible container management, you can automate complex development workflows without memorizing dozens of CLI commands. The skill system makes these workflows reusable and shareable across your team.

Start with the basic container management skill, then expand into specialized skills for your specific development needs. As you identify repetitive tasks, convert them into new skills—the more you automate, the more time you’ll save.

Remember to regularly update your skills as Podman introduces new features, and consider contributing your skills to the community to help others streamline their container workflows.

Built by theluckystrike — More at zovo.one