Bản viết lại dựa trên nguồn: https://www.docker.com/blog/reproducible-esp32-firmware-development-with-docker-and-docker-sandboxes/
ESP32 Firmware Development with Docker Sandboxes | Docker Skip to content Products AI and Agents Docker Sandboxes New Isolated environments for coding agents AI Governance New Govern agents and Claws across every team Gordon New Your AI Agent across Docker Docker Model Runner Local-first LLM inference made easy Docker MCP Catalog and Toolkit Connect and manage MCP tools Application Security Docker Hardened Images Ship with secure, enterprise-ready images Docker Scout Simplify the software supply chain Application Development Docker Desktop Containerize your applications Docker Hub Discover and share container images Docker Offload Break free of local constraints Support Developers Documentation Find guides for Docker products Getting Started Learn the Docker basics Resources Search a library of helpful materials Training Skill up your Docker knowledge Extensions SDK Create and share your own extensions Community Connect with other Docker developers Open Source Explore open source projects Preview Program Help shape the future of Docker Customer Stories Get inspired with customer stories Get the latest Docker news Pricing Yearly Monthly Docker Personal $0 $0 For individual developers who need the essential tools to build and deploy containers. Get started Get started Docker Pro $11 $9 per user/month For individual professionals who require more advanced features and additional resources. Buy now Buy now MOST POPULAR Docker Team $16 $15 per user/month For small teams that need collaborative tools to make working together more efficient. Buy now Buy now Docker Business $24 $24 per user/month For enterprises desiring robust security, control, and compliance features. Buy now Buy now Contact sales Contact sales Docker Hardened Images (DHI) Secure, minimal container images for every team, free with enterprise features, if needed. Start Free Trial BlogDocs Search Sign In Toggle menu Docker Captain Reproducible ESP32 Firmware Development with Docker and Docker Sandboxes Posted Aug 14, 2026 Marco Franzon 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 <feature>. The branch flag keeps the agent’s commits on a worktree, so your checkout stays clean; review and merge when it’s done. Multi-board testing: parallel containers (you) or parallel sandboxes (agents), one per device, with udev-stable names and one esp_rfc2217_server per board. CI: GitHub Actions with the official espressif/esp-idf-ci-action, pinned to the same IDF version as your dev image. If a build passes locally, it passes in CI. It’s the same bits. # .github/workflows/build.yml jobs: build: runs-on: ubuntu-latest steps: – uses: actions/checkout@v4 with: { submodules: recursive } – uses: espressif/esp-idf-ci-action@v1 with: esp_idf_version: v5.4 target: esp32s3 Pro Tips Pin exact image tags (release-v5.4, not latest), and record the tag in the repo (Makefile or compose file) so the toolchain version is part of the code review. One project folder per product line (new-feature/, legacy/) with its own pinned image. Never share a build/ directory between IDF versions. IDF_GIT_SAFE_DIR=/project kills the Git ownership warnings; IDF_CCACHE_ENABLE=1 plus a ccache volume kills the rebuild times. Add –group-add for the dialout GID when combining –device with -u $UID. On macOS/Windows, and always with sandboxes, RFC2217 is your serial transport. One server per board, one port per server. Put the flash/monitor commands and port mapping in CLAUDE.md so agents discover the hardware setup without being told each session. If your team standardizes on extra tools (clang-tidy, cppcheck, a particular esptool), bake a thin custom image FROM espressif/idf:release-v5.4 rather than installing them in every session. Conclusion Docker turned ESP32 builds from a fragile, machine-specific ritual into something reproducible enough to trust. Parallel containers turn one desk into a small hardware lab, with legacy and next-gen firmware coexisting without friction. And Docker Sandboxes close the last gap: they make it reasonable, not reckless, to hand an AI agent a real board and let it work. If you’re still installing ESP-IDF directly on your host machine in 2026, you’re working harder than necessary. Try the two-board setup this week: new firmware iterating on one device, stable firmware soaking on the other. Then hand one of them to an agent in a sandbox and see how far it gets. Happy hacking! Learn more ESP-IDF Docker image guide Review the Docker Sandboxes documentation Read the Docker blog about how to run Claude Code and other coding agents safely Review the GitHub action for building ESP-IDF projects: esp-idf-ci-action containers Docker Sandboxes Community Table of contents Related Posts Aug 18, 2026 17,600 Actions: Agent Security Is a Systems Problem The OpenAI/Hugging Face incident exposed a new challenge for AI agent security. 17,600 attacker actions show why AI agent security can’t rely on human review. Explore the controls needed to constrain, observe, and govern agents at speed. Mark Cavage Read now Aug 21, 2026 Running AI agents in GitHub Actions with Docker Sandboxes Run AI agents in GitHub Actions with Docker Sandboxes. See how isolated agents can run Testcontainers tests, fix code, and open draft pull requests. Oleg Selajev Read now Aug 20, 2026 Docker Verified Publisher Applications Are Now Self-Serve Apply to become a Docker Verified Publisher (DVP) now directly through Docker Hub. Get your verified content seen first by devs looking for trusted options. Julia Wilson and Dan Stelzer Read now Products Products Overview Docker Desktop Docker Hub Docker Scout Docker Build Cloud Docker MCP Catalog and Toolkit Docker Hardened Images Docker Sandboxes AI Governance Features Command Line Interface IDE Extensions Container Runtime Docker Extensions Trusted Open Source Content Secure Software Supply Chain Developers Documentation Getting Started Trainings Extensions SDK Community Open Source Preview Program Newsletter Pricing Personal Pro Team Business Premium Support and TAM Pricing FAQ Contact Sales Company About Us What is a Container Blog Why Docker Trust Customer Success Partners Events Docker System Status Newsroom Swag Store Brand Guidelines Trademark Guidelines Careers Contact Us Languages English 日本語 © 2026 Docker Inc. All rights reserved Terms of Use Privacy Legal Cookie Settings