Workbench for Zephyr - VS Code Docker Image & Dev Container

A Docker image that ships the official VS Code with the Workbench for Zephyr extension and the Zephyr host tools pre-installed, plus a Dev Container so you can develop against it from your local VS Code. The same image is meant to be reused in CI, so your local and CI environments match.

Everything is installed in VS Code's standard locations (no portable mode):

What	Location	Notes
Extensions	~/.vscode/extensions	default code extensions dir
User data	~/.config/Code	default code user-data dir
Host tools	~/.zinstaller	install.sh default base; holds env.sh

There are no VSCODE_DATA_DIR / VSCODE_EXTENSIONS_DIR overrides, the extension locates the host tools automatically through its built-in default setting zephyr-workbench.pathToEnvScript = "${userHome}/.zinstaller/env.sh".

The Zephyr SDK and a Zephyr source workspace are intentionally not baked into the image, add those from the Workbench UI (or west) on first run.

What the image contains

• Ubuntu 24.04 base
• Official VS Code (code, from Microsoft's apt repository)
• A non-root dev user (home /home/dev) with passwordless sudo
• The Ac6.zephyr-workbench extension (plus its dependencies: C/C++, CMake Tools, Serial Monitor, …) in ~/.vscode/extensions
• Zephyr host tools (CMake, Ninja, dtc, dfu-util, a Python venv with west, …) in ~/.zinstaller, installed by the extension's own scripts/hosttools/install.sh

Not included (install later from the Workbench UI): the Zephyr SDK/toolchains and any Zephyr source tree.

How it is built

The host tools are not apt-installed by hand. The Dockerfile installs the extension with the VS Code CLI (standard dirs) and then runs the extension's own installer, pointing it at $HOME so the tools land in ~/.zinstaller:

code --no-sandbox --install-extension Ac6.zephyr-workbench
bash ~/.vscode/extensions/ac6.zephyr-workbench-*/scripts/hosttools/install.sh "$HOME"

The installer provisions host tools only, it never installs the SDK or Zephyr sources, so --skip-sdk is unnecessary (and is not accepted by current versions).

Build

From the repo root:

docker build -t zephyr-workbench .

Open in a Dev Container (from your local VS Code)

This is the recommended way to access the environment from your local VS Code.

Prerequisites

• Docker Desktop running.
• The Dev Containers extension (ms-vscode-remote.remote-containers) installed in your local VS Code.

Steps

1. Open this folder (vscode-zephyr-workbench-docker) in VS Code.
2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Run Dev Containers: Reopen in Container. (First click in the bottom-left green corner → Reopen in Container also works.)

VS Code builds the image from the Dockerfile (first time only, the host-tools install takes a few minutes; later starts are cached), starts the container, and connects to a VS Code server it injects inside it. The Ac6.zephyr-workbench extension is installed into that server automatically and finds the baked-in host tools at ~/.zinstaller.

Verify it worked

Open an integrated terminal (Ctrl+`), you should see the (.venv) prompt, and run:

west --version

The Workbench for Zephyr view also appears in the activity bar; use it to add a Zephyr SDK and a West workspace (these are not baked into the image).

To leave the container: Command Palette → Dev Containers: Reopen Folder Locally.

Troubleshooting

• accessing specified distro mount service: stat /run/guest-services/distro-services/<distro>.sock: no such file or directory The image built, but docker run failed. On Windows, Dev Containers tries to bind-mount the WSLg Wayland socket (for Linux GUI apps) and Docker Desktop can't reach that WSL distro's mount service. The dev-container flow is headless and doesn't need it, disable the mount in your local VS Code user settings, then reload the window and retry:

  "dev.containers.mountWaylandSocket": false

Faster startup / shared CI: build and push the image once, then change .devcontainer/devcontainer.json from "build": { ... } to "image": "<your-registry>/zephyr-workbench:<tag>" so it pulls instead of rebuilding.

Run the GUI directly (standalone, no Dev Container)

The image's default command launches the VS Code GUI, so the host must provide an X display.

Linux host:

xhost +local:docker
docker run --rm -it \
  -e DISPLAY="$DISPLAY" \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  zephyr-workbench

Windows / macOS: run an X server (VcXsrv/X410 on Windows, XQuartz on macOS) and point DISPLAY at it:

docker run --rm -it -e DISPLAY=host.docker.internal:0.0 zephyr-workbench

On Windows with Docker Desktop (WSL2 backend), WSLg can also provide the display.

Use in CI / terminal-only

Override the default command to drop straight into a shell:

docker run --rm -it zephyr-workbench bash

The host tools are already on PATH (~/.zinstaller/env.sh is sourced from ~/.bashrc):

west --version
cmake --version
ninja --version

First run inside VS Code

1. Open the Workbench for Zephyr view in the activity bar.
2. Install a Zephyr SDK / toolchain.
3. Initialize or import a West workspace.
4. Create or import an application, then build.

Notes

• DONT_PROMPT_WSL_INSTALL=1 is set in the image: Docker Desktop runs containers in a WSL2 VM, so the code CLI would otherwise print an interactive "you appear to be in WSL" prompt that breaks the non-interactive build. Harmless on native Linux hosts.
• VS Code is launched with --no-sandbox because the Electron sandbox does not work in a typical container.
• To flash/debug real hardware over USB from the Dev Container, see the commented runArgs / mounts in .devcontainer/devcontainer.json (Linux host only; USB passthrough is limited on Windows/macOS).