A practical guide to building a real MLflow mixin kit from scratch, errors included.
Hey! Let me tell you something. When I first heard about Docker Sandbox Kits, my first reaction was: "Okay, another YAML thing. How hard can it be?"
Spoiler: it was harder than expected. But also way more interesting.
I'm Yhary, a Docker Captain and AI Engineer from Colombia. I recently built my first SBX kit as part of a Docker Captains community activity, and I want to walk you through the whole journey: what it is, why it matters, how I built it, and most importantly, every single thing that broke along the way.
Let's go.
First Things First: What Even Is a Docker Sandbox Kit?
Imagine you're an AI engineer. You spin up a new sandbox to run some experiments with Claude Code. But before you can actually do anything, you need to:
Every. Single. Time.
That's configuration drift. And it's been a problem since the 90s.
A Docker Sandbox Kit (SBX Kit) solves this. It's a declarative YAML file (spec.yaml
) that configures your sandbox environment automatically at creation time. One file. Reproducible. Shareable. No more "works on my machine."
Think of it like dotfiles + Infrastructure as Code, but specifically designed for AI agent sandboxes.
What a kit actually does
| Capability | Example |
|---|---|
| Installs tools | |
pip install mlflow , CLIs, binaries |
|
| Injects environment variables | MLFLOW_TRACKING_URI=http://localhost:5000 |
| Manages secrets securely | Tokens never enter the sandbox VM |
| Controls network access | Only allows pypi.org , blocks everything else |
| Runs startup scripts | Launches MLflow server automatically |
Two types of kits
kind: agent
: Defines a completely new agent from scratch. Has its own base image and entrypoint.
kind: mixin
: Extends an existing agent (like Claude Code) by layering new capabilities on top. Think of it as a plugin.
Put heavy, stable dependencies in the Docker image. Put everything that changes (credentials, network rules, startup commands) in the kit YAML.The golden rule:
Okay, Now Let's Build One
Enough theory. Let me show you what I built and how.
The goal: A mixin kit that automatically starts an MLflow tracking server when the sandbox is created, so Claude Code can log ML experiments, track metrics, and version models right out of the box.
Step 1: Plan the architecture
Before writing any YAML, I sketched the architecture:
SANDBOX (sbx)
Claude Code Agent
(orchestrates experiments via prompts)
MLflow Tracking Server
http://localhost:5000
SQLite backend + artifact store
~/.mlflow/mlflow.db
Claude Code talks to MLflow. MLflow persists everything to SQLite. Simple.
Step 2: Set up the folder structure
mlops-experiment-agent/
├── spec.yaml - The heart of the kit
├── Dockerfile - Base image with heavy dependencies
├── CLAUDE.md - Instructions for the Claude Code agent
├── scripts/
│ └── start-mlflow.sh
└── README.md
Step 3: Write the Dockerfile
Heavy dependencies go in the image not in the install hook. This way, creating a sandbox just pulls a layer instead of down gigabytes every time.
FROM --platform=linux/amd64 docker/sandbox-templates:shell-docker
USER root
RUN apt-get update && apt-get install -y \
software-properties-common \
curl \
build-essential \
pkg-config \
&& add-apt-repository ppa:deadsnakes/ppa -y \
&& apt-get update && apt-get install -y \
python3.11 \
python3.11-venv \
python3.11-dev \
&& rm -rf /var/lib/apt/lists/*
USER 1000
ENV PATH=/home/agent/.venv/bin:/home/agent/.local/bin:${PATH}
RUN python3.11 -m venv /home/agent/.venv && \
/home/agent/.venv/bin/pip install --no-cache-dir --upgrade pip && \
/home/agent/.venv/bin/pip install --no-cache-dir \
"numpy==1.26.4" \
"pandas==2.2.2" \
"scikit-learn==1.4.2" \
"mlflow==2.13.0" \
"boto3"
Step 4: Write CLAUDE.md
This file tells Claude Code what tools are available inside the sandbox:
You are an ML experiment orchestrator. MLflow is running at http://localhost:5000.
## Your capabilities
- Log experiments: `mlflow.start_run()`, `mlflow.log_param()`, `mlflow.log_metric()`
- Register models: `mlflow.sklearn.log_model()`
- Compare runs via the MLflow UI or Python client
- Version datasets using MLflow's dataset tracking
## Common tasks you can do
- "Run a baseline experiment with this dataset"
- "Compare the last 3 runs by accuracy"
- "Register the best model to the Model Registry"
- "Show me all experiments logged today"
## MLflow UI
Available at: http://localhost:5000
Step 5: Write the spec.yaml
This is the final kit manifest after all the debugging (more on that below):
schemaVersion: "1"
kind: mixin
name: mlops-mixin
displayName: MLOps Experiment Agent
description: >
Orchestrates ML experiments inside a Docker Sandbox. Tracks runs,
logs metrics and parameters, versions models using MLflow.
Ideal for classification and CV pipelines.
environment:
variables:
MLFLOW_TRACKING_URI: "http://localhost:5000"
MLFLOW_EXPERIMENT_NAME: "sandbox-experiments"
network:
allowedDomains:
- "pypi.org:443"
- "files.pythonhosted.org:443"
commands:
install:
- command: "pip install --break-system-packages --upgrade pip && pip install --break-system-packages 'numpy>=2.0' 'pandas>=2.0' 'scikit-learn>=1.5' 'mlflow>=2.13' boto3 && sed -i 's/from importlib.abc import Traversable/from importlib.resources.abc import Traversable/' /home/agent/.local/lib/python3.14/site-packages/mlflow/assistant/skill_installer.py"
user: "1000"
description: "Install MLflow and ML dependencies and patch Python 3.14 compatibility"
startup:
- command: ["sh", "-c", "mkdir -p /home/agent/.mlflow/artifacts && setsid /home/agent/.local/bin/mlflow server --backend-store-uri sqlite:////home/agent/.mlflow/mlflow.db --default-artifact-root /home/agent/.mlflow/artifacts --host 0.0.0.0 --port 5000 > /home/agent/.mlflow/server.log 2>&1 &"]
user: "1000"
description: "Start MLflow tracking server"
Step 6: Build and publish the Docker image
On Apple Silicon (M1/M2/M3) you need to build for multiple architectures:
docker buildx create --name multiarch-builder --use
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t yharyarias/mlops-experiment-agent:latest \
--push .
Step 7: Stage and publish the kit
mkdir -p /tmp/kit-stage/mlops-experiment-agent
rsync -a \
--exclude '.git' --exclude '.venv' --exclude '.sbx' \
--exclude '*.tar' --exclude '.DS_Store' --exclude '__pycache__' \
./mlops-experiment-agent/ /tmp/kit-stage/mlops-experiment-agent/
sbx kit push /tmp/kit-stage/mlops-experiment-agent \
docker.io/yharyarias/mlops-experiment-agent-kit:latest
Important:sbx kit push packages the directory exactly as it is, it does NOT respect .gitignore. Always stage a clean copy first. If you have a .venv or .sbx/.env with real secrets, they will be published.
Step 8: Run it!
sbx run \
--kit docker.io/yharyarias/mlops-experiment-agent-kit:latest \
--name mlops-sandbox \
claude
Then verify from a second terminal:
sbx exec mlops-sandbox -- curl -s http://localhost:5000/health
sbx exec mlops-sandbox -- cat /var/log/sbx-kit-startup.log
sbx exec mlops-sandbox -- cat /home/agent/.mlflow/server.log
The Errors (This Is the Good Part)
Let me be honest with you. Nothing worked on the first try. Here's every error I hit and how I fixed it.
Error 1: PEP 668: pip won't install system packages
note: If you believe this is a mistake, please contact your Python installation or OS
distribution provider. You can override this, at the risk of breaking your Python
installation or OS, by passing --break-system-packages.
What happened: Modern Ubuntu protects the system Python from pip installs.
Fix:
pip install --break-system-packages mlflow scikit-learn pandas numpy boto3
Error 2: NumPy has no wheel for Python 3.14
Cannot compile Python.h
. Perhaps you need to install python-dev|python-devel
Project name: NumPy
Project version: 1.26.4
Run-time dependency python found: YES 3.14
Has header "Python.h" with dependency python: NO
What happened: The sandbox base image uses Python 3.14. NumPy 1.26.4
has no prebuilt wheel for Python 3.14
, it tries to compile from source and fails.
Fix: Use numpy>=2.0
which has prebuilt wheels for Python 3.14:
pip install --break-system-packages 'numpy>=2.0' 'pandas>=2.0' 'scikit-learn>=1.5' 'mlflow>=2.13'
Error 3: Apple Silicon platform mismatch
no match for platform in manifest sha256:dd0618b...: not found
What happened: Building on Mac M1/M2/M3 produces an aarch64 image. The sbx runtime expected a multi-arch manifest.
Fix: Use docker buildx to build for both platforms:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t yharyarias/mlops-experiment-agent:latest \
--push .
Error 4: MLflow ImportError on Python 3.14
ImportError: cannot import name 'Traversable' from 'importlib.abc' File ".../mlflow/assistant/skill_installer.py", line 11, in from importlib.abc import Traversable
What happened: importlib.abc.Traversable was removed in Python 3.14 and moved to importlib.resources.abc. MLflow hadn't been updated yet.
The cool part: Claude Code actually found and fixed this bug by itself inside the sandbox, it patched skill_installer.py
automatically.
Fix: Apply a sed
patch in the install hook:
sed -i 's/from importlib.abc import Traversable/from importlib.resources.abc import Traversable/' \
/home/agent/.local/lib/python3.14/site-packages/mlflow/assistant/skill_installer.py
Error 5: Background process dies during startup
setsid: failed to execute mlflow: No such file or directory
What happened: Two issues at once:
The PATH
is not set during startup hooks, so mlflow
can't be found by name
Background processes started without setsid
die when the startup session ends
Fix: Use the absolute path and always prefix with setsid:
nohup mlflow server ... &
setsid /home/agent/.local/bin/mlflow server ... > /home/agent/.mlflow/server.log 2>&1 &
Error 6: MLflow directory doesn't exist at startup
What happened: MLflow tried to create its database before the artifact directory existed, and failed silently.
Fix: Create the directory in the same startup command, before MLflow runs:
mkdir -p /home/agent/.mlflow/artifacts && setsid /home/agent/.local/bin/mlflow server ...
Key Takeaways
sbx exec <sandbox> -- cat /var/log/sbx-kit-startup.log
sbx exec <sandbox> -- cat /home/agent/.mlflow/server.log
docker run --rm -u '1000' 'docker/sandbox-templates:claude-code-docker' \
sh -c 'your install command here'
Try It Yourself
The kit is live on Docker Hub. Just run:
sbx run \
--kit docker.io/yharyarias/mlops-experiment-agent-kit:latest \
--name mlops-sandbox \
claude
MLflow will start automatically on port 5000. Then you can prompt Claude Code with things like:
Run a baseline logistic regression on the iris dataset and log the results to MLflow Compare the last 3 MLflow runs by accuracy Register the best model to the Model Registry
Links