Claude Code Podman Container

A rootless Podman container setup for Claude Code development environment with Python support.

Features

• Rootless Operation: Runs without root privileges for enhanced security
• Python Development: Pre-configured with Python, pyenv, and development tools
• Claude Integration: Ready for Claude AI coding assistant
• Persistent Storage: Workspace directory and configuration volumes
• Security Hardened: Capability restrictions, resource limits, and SELinux/AppArmor isolation

Requirements

For Podman (recommended):

• Podman (rootless setup recommended)
• Linux system with user namespace support
• At least 8GB RAM and 4 CPU cores available

For Docker:

• Docker Engine
• At least 8GB RAM and 4 CPU cores available
• Use the --docker option to enable Docker support

Installation

1. Install Podman

# Ubuntu/Debian
sudo apt-get install podman

# Fedora
sudo dnf install podman

# Arch Linux
sudo pacman -S podman

2. Clone this repository

git clone https://git.aquila-consortium/guilhem_lavaux/contain-claude.git
cd contain-claude

3. Make the script executable

chmod +x start-claude-podman.sh

Usage

Start the container

./start-claude-podman.sh

Options

• Show help: ./start-claude-podman.sh --help or ./start-claude-podman.sh -h
• Use Docker: ./start-claude-podman.sh --docker (use Docker instead of Podman)
• Rebuild container: ./start-claude-podman.sh --rebuild or ./start-claude-podman.sh -r
• Restart container: ./start-claude-podman.sh --restart
• Stop container: ./start-claude-podman.sh --stop (stop running container without starting)
• Dry run: ./start-claude-podman.sh --dry-run (show configuration without starting)
• Custom memory: ./start-claude-podman.sh -m 16g (set memory limit)
• Custom CPUs: ./start-claude-podman.sh -c 8 (set CPU limit)
• Custom container name: ./start-claude-podman.sh -n my-container
• Custom image name: ./start-claude-podman.sh -i my-image
• Custom workspace: ./start-claude-podman.sh -w /path/to/workspace
• Debug mode: ./start-claude-podman.sh --debug (show detailed configuration)

Examples

# Start with default settings (Podman)
./start-claude-podman.sh

# Use Docker instead of Podman
./start-claude-podman.sh --docker

# Rebuild image and start
./start-claude-podman.sh --rebuild

# Custom resource limits
./start-claude-podman.sh -m 16g -c 8

# Custom container name and workspace
./start-claude-podman.sh -n my-dev-container -w ./my-workspace

# Show configuration without starting
./start-claude-podman.sh --dry-run -m 32g -c 12

# Stop running container
./start-claude-podman.sh --stop

# Debug mode with rebuild
./start-claude-podman.sh --debug --rebuild

# Stop container with custom name
./start-claude-podman.sh --stop -n my-container

# Docker with custom resources
./start-claude-podman.sh --docker -m 16g -c 8 -n docker-container

They can be stacked

Configuration

Environment Variables

You may set (optional) ANTHROPIC_API_KEY before running:

export ANTHROPIC_API_KEY="your-api-key-here"
./start-claude-podman.sh

Or enter it when prompted during first run.

Workspace Directory

The script creates a workspace/ directory in the current folder that is mounted into the container at /workspace.

Container Details

• Image: Ubuntu 25.04 based (customizable via -i option)
• User: claude (non-root)
• Python: pyenv with multiple Python versions available
• Tools: git, curl, build-essential, ccache, SQLite, OpenSSL
• Resource Limits: 8GB RAM (customizable via -m option), 4 CPUs (customizable via -c option)
• Security: Podman rootless mode includes capability restrictions, SELinux/AppArmor isolation, and PID limits (200 processes)
• Docker Support: Full compatibility with Docker Engine via --docker option

Security Features

• ✅ Rootless container execution
• ✅ SELinux/AppArmor isolation
• ✅ Capability restrictions (only necessary capabilities)
• ✅ No new privileges flag
• ✅ Resource limits enforced
• ✅ User namespace isolation

Development Workflow

1. Enter container: podman exec -it claude-code-workspace bash
2. Use Claude: Run claude command inside container
3. Python development: Use pyenv to manage Python versions
4. Exit container: Type exit or press Ctrl+D

Cleanup

To stop and remove the container:

podman stop claude-code-workspace
podman rm claude-code-workspace

To remove the image:

podman rmi claude-code-podman

Troubleshooting

Podman not installed

Ensure Podman is installed and in your PATH. The script will show installation instructions if Podman is missing.

Resource constraints

If you get resource errors, adjust the --memory and --cpus parameters in the script.

License

MIT License

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Support

For issues or questions, please open a Forgejo issue.