MCU-Debug Proxy Server

Pre-release software

There is no release version yet. In VS Code, install using the dropdown beside Install and choose Install Pre-Release Version — plain Install reports that no release exists before offering you the pre-release, which is about the release channel rather than a broken listing.

Companion extension for MCU-Debug. Install it on the machine your debug probe is physically plugged into, and MCU-Debug can drive that probe from an editor running somewhere else — inside WSL, a dev container, or on another machine over SSH.

This extension does nothing on its own. It has no UI and no debug configuration of its own. It exists so that the main MCU-Debug extension can reach a probe that is not on the same machine as your source code.

Do I need it?

You most likely arrived here because MCU-Debug offered to install it. MCU-Debug looks for this extension at runtime, and only for a configuration that actually needs it — one reaching a probe on a different machine than your workspace. When it is needed and missing, you are told why and offered the install. Purely local debugging never asks, and having it installed anyway costs you nothing: no UI, nothing running.

⚠️ Uninstalling it no longer breaks MCU-Debug, but keeping it is still the easier path. Up to v0.1.14 this extension was a declared dependency and VS Code refused to load MCU-Debug without it. That is gone — it could never be satisfied in a remote workspace, which broke MCU-Debug there entirely. Today a missing proxy only costs you a prompt at the moment you next need remote debugging. The reason to leave it installed is that the two are versioned in lockstep and are expected to match: kept in place, it updates alongside MCU-Debug on its own.

How it works

Your workspace — source, compilers, launch.json, GDB — stays where it is. The probe stays where it is. This extension runs next to the probe and presents it to the debug adapter as though it were local.

   Workspace  (WSL / container / laptop)          Probe host  (Windows / lab server)
  ┌──────────────────────────────────┐          ┌──────────────────────────────────┐
  │  Source, compilers, launch.json  │          │  MCU-Debug Proxy Server          │
  │  MCU-Debug extension             │          │    (this extension)              │
  │  Debug Adapter                   │          │        │                         │
  │  GDB                             │          │        ▼                         │
  │  Views: RTT, SWO, UART,          │          │  gdb-server (OpenOCD, J-Link…)   │
  │         Memory, RTOS, SVD        │          │        │                         │
  │            │                     │          │        ▼                         │
  │       Proxy Client ──────────────┼──────────┼──▶  Debug Probe  ──▶  MCU        │
  └──────────────────────────────────┘          └──────────────────────────────────┘

The proxy owns the gdb-server lifecycle on the probe side and tunnels GDB, RTT, SWO and serial traffic back to the workspace, so telemetry appears in your editor exactly as it would locally.

Where it gets installed

VS Code decides this for you, and it is worth knowing why it looks backwards. This extension is marked as a UI extension, so when you open a folder in WSL or a container, VS Code keeps it on your host machine and copies only the main MCU-Debug extension into the remote environment. That is the correct split: the proxy has to run where the probe is.

For WSL and dev containers, the connection is detected automatically. For a lab server, point hostConfig at it in your launch.json and the extension deploys and starts what it needs over SSH.

Supported topologies

Full guide: Remote Debugging.

Commands

Normally you never invoke these — the main extension starts what it needs when a debug session begins. They exist for diagnostics and for setups that need a proxy running ahead of time.

Status

This extension is in preview and is versioned in lockstep with MCU-Debug, so the two always install as a matched pair. Please report anything that misbehaves — remote setups vary enormously and real-world reports are the most useful thing we can get.

• Issues
• Changelog

License

Apache-2.0. See LICENSE.