Reproducible ESP32 Firmware Development with Docker and Docker Sandboxes Docker and Docker Sandboxes can solve ESP32 firmware development reproducibility and enable safe AI coding agent sessions, according to a technical guide. The official espressif/idf Docker image provides pinned ESP-IDF installations for clean builds, while the sbx CLI allows AI agents to work on firmware without full laptop access. The article details commands for building, flashing, and monitoring, including a network serial bridge for macOS and Windows, and recommends pinning image tags and using a Makefile for stability. Firmware development has always been challenging: mismatched toolchains, “it works on my machine” builds, and the tension between maintaining legacy products and shipping new features. In this article we explore how you can use Docker and Docker sandboxes to ease firmware development, especially for ESP32 projects. Nowadays, teams end up supporting multiple hardware revisions, several ESP-IDF releases, and long-term customer deployments, all while iterating on new capabilities like Wi-Fi 6, Matter, or power optimizations. The official espressif/idf Docker image solves the reproducibility problem. Docker Sandboxes the sbx CLI solve a newer one: letting AI coding agents work on your firmware at full speed without giving them the keys to your laptop. This article walks through a practical workflow that combines both: clean builds, parallel environments for new and legacy firmware, and safe unsupervised AI sessions. Part 1: The Baseline – Building with the Official Image The espressif/idf image ships a complete, pinned ESP-IDF installation: the framework itself, the Xtensa/RISC-V toolchains, Python environment, CMake, ninja, everything. A build needs one command: docker run --rm -v $PWD:/project -w /project \ -u $UID -e HOME=/tmp \ espressif/idf:release-v5.4 idf.py build A few details worth understanding rather than cargo-culting: -u $UID -e HOME=/tmp makes the container run as your user, so build artifacts in build/ aren’t owned by root. HOME=/tmp gives the IDF tools a writable home for their caches. Pin your tag. latest tracks the master branch and will break you eventually. vX.Y tags are fixed releases; release-vX.Y tags track the release branch and receive bugfixes. For products in maintenance, exact vX.Y.Z tags are the safest; for active development, release-vX.Y is a good balance.- If your mounted project is owned by a different user than the one in the container, Git will complain about “dubious ownership”. The image supports -e IDF GIT SAFE DIR='/project' to whitelist the path use : to separate multiple paths . - Enable the compiler cache with -e IDF CCACHE ENABLE=1 and persist it across runs by mounting a volume for it. Full rebuilds of a mid-size project drop from minutes to seconds. Flashing and monitoring On Linux , pass the serial device through: docker run --rm -it \ --device=/dev/ttyUSB0 \ --group-add $ getent group dialout | cut -d: -f3 \ -v $PWD:/project -w /project \ -u $UID -e HOME=/tmp \ espressif/idf:release-v5.4 idf.py flash monitor The --group-add is needed because you’re running as $UID , not root, and the device node belongs to dialout . On macOS and Windows , Docker Desktop cannot pass USB devices into containers. The clean workaround is a network serial bridge using RFC2217, which esptool supports natively. On the host: pip install esptool esp rfc2217 server -p 4000 /dev/cu.usbserial-1420 Inside the container, point idf.py at the network port: idf.py --port 'rfc2217://host.docker.internal:4000?ign set control' flash monitor This looks like a hack but it’s actually a feature: once the serial port is a network endpoint, anything can reach it. Containers, CI runners, and as we’ll see sandboxed AI agents. Keep this trick in mind; it’s the linchpin of Part 3. Hide it behind a Makefile Nobody should type these commands twice. A small Makefile keeps the interface stable even if the plumbing changes: IDF IMAGE ?= espressif/idf:release-v5.4 PORT ?= /dev/ttyUSB0 DOCKER RUN = docker run --rm -it \ --device=$ PORT \ --group-add $ shell getent group dialout | cut -d: -f3 \ -v $ PWD :/project -w /project \ -v idf-ccache:/ccache -e CCACHE DIR=/ccache -e IDF CCACHE ENABLE=1 \ -u $ shell id -u -e HOME=/tmp -e IDF GIT SAFE DIR=/project \ $ IDF IMAGE build: $ DOCKER RUN idf.py build flash: $ DOCKER RUN idf.py flash monitor: $ DOCKER RUN idf.py monitor menuconfig: $ DOCKER RUN idf.py menuconfig shell: $ DOCKER RUN bash Now make build works identically for every developer and in CI, and switching IDF versions is make build IDF IMAGE=espressif/idf:release-v5.3 . Part 2: Parallel Environments – New Features and Legacy, Side by Side This is where the container approach stops being merely convenient and starts changing how you work. Because each container is fully isolated, you can run two different IDF versions against two different boards at the same time, on the same machine. Terminal 1 - new feature branch, IDF 5.4, experimental board docker run --rm -it --device=/dev/esp32-experimental \ -v $PWD/new-feature:/project -w /project \ -u $UID -e HOME=/tmp \ espressif/idf:release-v5.4 Terminal 2 - legacy firmware, IDF 5.3, production board docker run --rm -it --device=/dev/esp32-production \ -v $PWD/legacy:/project -w /project \ -u $UID -e HOME=/tmp \ espressif/idf:release-v5.3 Typical uses: flashing experimental code on one board while a long-running soak test or customer demo stays untouched on the other; A/B-comparing power consumption between firmware versions; reproducing a field bug on the exact legacy toolchain while the fix is developed on the current one. Stable device names with udev /dev/ttyUSB0 and /dev/ttyUSB1 swap depending on plug order, which will eventually make you flash the wrong board. On Linux, pin them with udev rules keyed on the adapter’s serial number: find the serial numbers udevadm info -a /dev/ttyUSB0 | grep '{serial}' /etc/udev/rules.d/99-esp32.rules SUBSYSTEM=="tty", ATTRS{serial}=="A50285BI", SYMLINK+="esp32-experimental" SUBSYSTEM=="tty", ATTRS{serial}=="B7743NM0", SYMLINK+="esp32-production" After udevadm control --reload , the symlinks survive reboots and re-plugs, and your Makefile targets can reference boards by role instead of by enumeration accident. Or codify it with Compose If the two-environment setup is permanent, a compose.yaml documents it better than shell history: services: new-feature: image: espressif/idf:release-v5.4 volumes: "./new-feature:/project" working dir: /project devices: "/dev/esp32-experimental:/dev/ttyUSB0" stdin open: true tty: true legacy: image: espressif/idf:release-v5.3 volumes: "./legacy:/project" working dir: /project devices: "/dev/esp32-production:/dev/ttyUSB0" stdin open: true tty: true docker compose run new-feature idf.py flash monitor and the mapping from role to physical board is version-controlled. Part 3: Docker Sandboxes – Letting AI Agents Work Unsupervised Coding agents like Claude Code are genuinely useful for firmware work: porting components between IDF versions, writing unit tests, chasing config drift in sdkconfig . But to be useful they need to run things : builds, flashes, pip install , sometimes Docker itself. Giving an agent that freedom directly on your host, in bypass-permissions mode, is uncomfortable for good reasons. Docker Sandboxes solve this with a stronger primitive than a container: each sandbox is a microVM with its own kernel, filesystem, network stack, and its own private Docker daemon . The agent can install packages, modify system config, build and run containers, and none of it touches your host. Your workspace directory syncs into the sandbox at the same path, so file paths in error messages match between the two worlds. The CLI is small and clear: start Claude Code in a sandbox for the current project sbx run claude work on a specific directory sbx run claude ~/firmware/new-feature see what's running, resource usage, network requests sbx list and clean up sbx ls sbx rm new-feature Three properties matter for firmware work in particular: Disposability. The agent can trash its environment experimenting with esptool versions, partition tables, or custom toolchains. sbx rm and it never happened. Your host IDF setup, if you even have one, is untouched. Network policy. Sandboxes route traffic through a host-side proxy with three modes: open , balanced default-deny with pre-approved developer and package-manager domains , and locked down . An agent that decides to curl your firmware to somewhere unexpected simply can’t. Credential isolation. API keys and tokens are injected by the host-side proxy into outgoing requests; the sandbox itself never sees them. A prompt-injected agent can’t exfiltrate what it doesn’t have. But how does the agent flash a board? Here’s where the RFC2217 trick from Part 1 pays off. The sandbox is a VM; there is no USB passthrough. But there is a network path to the host. So expose the serial port as a network service on the host: esp rfc2217 server -p 4000 /dev/esp32-experimental and tell the agent in your project’s CLAUDE.md or equivalent to flash with: idf.py --port 'rfc2217://host.docker.internal:4000?ign set control' flash monitor Now the agent’s whole loop runs end-to-end inside the sandbox: edit, build in a container it spawned itself, flash real hardware, read the monitor output, fix the bug. The only thing it can reach on your machine is one serial port you explicitly published. That’s a remarkably good trade: full hardware-in-the-loop autonomy, minimal blast radius. Run one sandbox per board and you get the parallel-environment pattern from Part 2, agent edition: an agent iterating on the experimental board via port 4000 while you, or a second locked-down agent, watch the production board via port 4001. Honest caveats Sandboxes are newer technology than containers, and it shows in places. MicroVM isolation is available on macOS Apple Silicon , Windows 11, and Linux with KVM. Build performance inside the microVM is noticeably slower than native containers: fine for agent sessions, annoying for your own tight inner loop. And the agent runs in bypass-permissions mode by design; the isolation is the permission system, so review the diff before merging, same as you would for any contributor. Part 4: Putting It Together – A Daily Workflow Regular development: VS Code Dev Containers with the espressif/idf image plus the Espressif IDF extension inside the container . Same image as CI, full IntelliSense, native-container speed. AI-assisted experimentation: sbx run claude --branch