I set up my first Docker SBX kit, and here's how I did it

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: Install your ML libraries Set up your environment variables Start your tracking server Configure your network rules 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. The golden rule: Put heavy, stable dependencies in the Docker image. Put everything that changes (credentials, network rules, startup commands) in the kit YAML. 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 downloading 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: # MLOps Experiment Agent 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: # Create a multi-arch builder docker buildx create --name multiarch-builder --use # Build and push to Docker Hub for both platforms docker buildx build \ --platform linux/amd64,linux/arm64 \ -t yharyarias/mlops-experiment-agent:latest \ --push . Step 7: Stage and publish the kit # Stage a clean copy, sbx kit push ignores .gitignore! 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/ # Publish as an OCI artifact 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: # Is MLflow running? sbx exec mlops-sandbox -- curl -s http://localhost:5000/health # Check the startup log sbx exec mlops-sandbox -- cat /var/log/sbx-kit-startup.log # Check the MLflow server 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: # Wrong nohup mlflow server ... & # Correct 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 Pin to versions with prebuilt wheels. If your sandbox runs Python 3.14, don't pin to NumPy 1.26, check which versions have wheels for your target platform first. Use setsid + absolute paths for background processes. Every time, no exceptions. Stage before pushing. sbx kit push ignores .gitignore. Use rsync with excludes. Check the logs when something fails: sbx exec -- cat /var/log/sbx-kit-startup.log sbx exec -- cat /home/agent/.mlflow/server.log Test your install command locally using the hint Docker gives you on failure: 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 Docker Hub: yharyarias/mlops-experiment-agent-kit PR on sbx-kits-contrib: #111 - Yharyarias mlops mixin Docker SBX Docs: docs.docker.com/ai/sandboxes