container-magic

Define your container workflow in a single YAML file. Container-magic generates a Dockerfile, build script, and run script that work with Docker or Podman - container-magic is not a dependency of your final product.

How It Works

You write a cm.yaml. Container-magic generates a Dockerfile, build.sh, and run.sh from it. These generated files are committed to your repository so that anyone can build and run the project with Docker or Podman.

For development, cm build and cm run read the config directly and handle workspace mounting, user identity mapping, and runtime features automatically.

Quick Start

pip install container-magic
cm init python:3.11 my-project
cd my-project
cm build
cm run python --version

On Nix, run it without installing - or add it as a flake input:

nix run github:markhedleyjones/container-magic -- init python:3.11 my-project
nix profile install github:markhedleyjones/container-magic   # install cm

The flake exposes packages.default / apps.default (the cm CLI) and an overlays.default for declarative setups.

A minimal cm.yaml:

names:
  image: my-project
  workspace: workspace
  user: nonroot

stages:
  base:
    from: python:3.11-slim
    steps:
      - apt-get:
          install:
            - git
            - build-essential
      - pip:
          install:
            - numpy
            - pandas

  development:
    from: base

  production:
    from: base

Build and run the production image:

./build.sh
./run.sh python workspace/train.py

Key Features

Development and production from one config - live-mounted workspace in dev, baked-in code in prod
Automatic user handling - host user identity in dev, dedicated user in prod, no manual setup
GPU, display, and audio - NVIDIA GPU passthrough, X11/Wayland forwarding, PulseAudio/PipeWire
Custom commands - define once, use in both dev and prod with port publishing and environment variables
Multi-stage builds - share steps between stages, pip packages install into the base image's Python (no venv duplication)
Transparent execution - run commands from anywhere in your repo with automatic path translation
Data volumes - shorthand for sibling folders (outputs, cache) that persist across runs without entering the image
AWS credential forwarding - mount host AWS config into the container
Cached assets - download models and datasets once, reuse across builds

Documentation

Full documentation is available at markhedleyjones.com/container-magic.

Page	Contents
Getting Started	Installation, first project, workflow
Configuration	Full YAML reference - names, runtime, stages, commands
Build Steps	Package managers, custom commands, layer caching
Cached Assets	Asset downloading, caching, and cache management
User Handling	Dev vs prod users, copy ownership, permissions
Troubleshooting	Common issues and solutions

Contributing

Contributions and feedback welcome! Open an issue or pull request on GitHub.

Metadata

Release files for container-magic 5.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for container-magic 5.8.0
File	Size	Uploaded
container_magic-5.8.0.tar.gz	50.9 kB	Jun 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for container-magic 5.8.0
File	Interpreter	ABI	Platform	Reset
container_magic-5.8.0-py3-none-any.whl 59.3 kB Jun 3, 2026	Python 3	none	any	Details

Total release size: 110.2 kB

Release files / container_magic-5.8.0.tar.gz

Download URL	container_magic-5.8.0.tar.gz
Size	50.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`b78cac6c064c98848add96629aa2f44ee432301a0acfec8a3e36e13f299d0a8b`
BLAKE2b-256 checksum How to use checksums	`00be2ddbaf3f92799fc2512939bd3e663f903e43df9c1789c5f35c1b76b7c223`
Upload date	Jun 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/markhedleyjones/container-magic
Publishing commit: github.com/markhedleyjones/container-magic/tree/7502477808616c8c7269af94804e9ea1603ae867

Workflow

Publishing configuration: github.com/markhedleyjones/container-magic/blob/7502477808616c8c7269af94804e9ea1603ae867/.github/workflows/ci.yml
Publishing logs: github.com/markhedleyjones/container-magic/actions/runs/26883865958/attempts/1

Artifact

Subject: container_magic-5.8.0.tar.gz
SHA-256 checksum: b78cac6c064c98848add96629aa2f44ee432301a0acfec8a3e36e13f299d0a8b Verifying attestations

Release files / container_magic-5.8.0-py3-none-any.whl

Download URL	container_magic-5.8.0-py3-none-any.whl
Size	59.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e92387da6dd6c40f201600cc48b9f573f53cf3cdbaab0f1a7e2fa71b3fe3cd9e`
BLAKE2b-256 checksum How to use checksums	`ce09b4969ae85f59b06f32709e7d1f4e2fd4c8c63d240f264f9c642b93a143bd`
Upload date	Jun 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/markhedleyjones/container-magic
Publishing commit: github.com/markhedleyjones/container-magic/tree/7502477808616c8c7269af94804e9ea1603ae867

Workflow

Publishing configuration: github.com/markhedleyjones/container-magic/blob/7502477808616c8c7269af94804e9ea1603ae867/.github/workflows/ci.yml
Publishing logs: github.com/markhedleyjones/container-magic/actions/runs/26883865958/attempts/1

Artifact

Subject: container_magic-5.8.0-py3-none-any.whl
SHA-256 checksum: e92387da6dd6c40f201600cc48b9f573f53cf3cdbaab0f1a7e2fa71b3fe3cd9e Verifying attestations