サインイン
Docker Captain

Reproducible ESP32 Firmware Development with Docker and Docker Sandboxes

投稿日 8月 14日, 2026年
マルコ・フランソン

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:

  1. 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.
  2. 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.
  3. 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.

結論

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.

ハッピーハッキング!

詳しく見る

Community

関連記事