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

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

Tópico: I set up my first Docker SBX kit, and here's how I did it
Categoria: Tutoriais | Programação & Tecnologia
Idioma Principal: Português (Conteúdo de Tecnologia)

Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
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 <sandbox> -- cat /var/log/sbx-kit-startup.log
sbx exec <sandbox> -- 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