WSL, Windows, TCB and the VS Code Extension

Technical Support
, , , ,
1

This question is sort of a “best practices” information request.

I have a few projects (folders) connected to their own GIT repos that I use to build my device. To keep it simple, let’s say I have:

~/code/my-codec = kernel module
~/code/my-app = dotnet web app in a container
~/code/my-app-2 = another app
~/code/my-device-trees = forked from [toradex/device-trees]
~/code/my-os = tcbuild.yaml is here, plus my /etc changes, for TCB

I use a Win 11 machine and WSL 2.

I usually work with the folder structure inside WSL 2 (standard Ubuntu install). I write my code there, commit to git from there, etc. I typically use VSCode pointed to the WSL 2 distro.

I then install TCB inside of ~/code. I don’t like git submodules. TCB doesn’t work with Symlinks, so this folder structure allows me to use TCB properly, and to keep all of my components in their own repos.

In order to use the VSCode extension, I’d prefer to use my own WSL distro, and not the new Torizon one, so I was able to follow the manual setup.

Now for my issues, questions:

  1. If I use Docker Desktop on my Windows PC, I am able to get the VS Code extension to work. However, I get an error trying to create my bundles.
  2. If I use the Docker Engine on my Windows PC, and a docker install on my WSL 2 Ubuntu, I can create my bundles. However, in this setup, I have not been able to get the self-hosted repository to work, specifically, the device cannot pull from it.

I’m open to suggestions for how to proceed. I’d prefer to keep my WSL 2 Ubuntu setup, along with the folders (git repos), and I’d prefer to not add another WSL distro for the VS Code Extension.

2

Hi, I’m the Toradex AI Assistant.

I might make mistakes. Our support team will step in if needed. If I answered your question, please tick the “Solution” checkbox. For follow-up questions to me, please use @ToradexAI in your post.

Did you like my answer? :+1: :-1:

Hello! Thank you for sharing the details of your workflow and setup. Your WSL 2-based approach with separate repositories per project is sound and aligns with flexible embedded Linux development.

Let’s break down your two main issues and propose best-practices to achieve stable development with your preferences:

1. Bundle Creation Errors with Docker Desktop

Problem:
With Docker Desktop for Windows, the Torizon VS Code Extension works for general development but fails during bundle creation.

Insights:

  • Bundle creation and deployment often require the Docker environment (and its registry) to be reachable from both your WSL 2 Ubuntu (where you’re working) and your Toradex device.
  • Docker Desktop presents containers on Windows, but WSL 2 needs proper integration to access these.
  • Even with Windows-Wide integration, network or filesystem mapping can cause issues, as outlined in the documentation.

2. Self-Hosted Registry Issues with Native Docker in WSL 2

Problem:
Running Docker natively inside WSL 2 allows bundle creation with TorizonCore Builder, but your device cannot access the self-hosted Docker registry for image deployment.

Cause:

  • By default, containers running inside a WSL 2 distro are not exposed to the Windows LAN.
  • The device (on your network) cannot reach the registry unless the WSL ports are explicitly forwarded.

Solution:
The VS Code Extension provides a script .conf/share-wsl-ports.xsh to set up port forwarding from WSL 2 to your Windows host, which is necessary for the target device to access the registry. Details are highlighted here:

  • Run the share-wsl-ports task in the VS Code extension, or manually set up forwarding (e.g., for port 5000) to make your WSL-hosted registry visible on your LAN.

    netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=5000 connectaddress=<WSL-IP> connectport=5000

  • Replace <WSL-IP> with the actual IP of your WSL 2 environment (e.g., wsl hostname -I).

  • Ensure Windows Firewall rules allow inbound connections to the forwarded port.

References:
Details and background:

Recommended Workflow

  • Continue using your WSL 2 Ubuntu install and existing folder/repo structure.
  • Run both Visual Studio Code and Docker Engine inside your WSL 2 Ubuntu.
    • This keeps source code and build artifacts in one environment.
  • For self-hosted registry and cross-device deployment:
    • Use the port forwarding method to expose the registry to your LAN.
    • Trigger the share-wsl-ports task from the extension before deploying to the board.
  • Maintain your manual setup:
    • No need for the new Torizon WSL Distro unless you want a managed environment.

Troubleshooting Tips

  • Check the Output panel in VS Code for extension errors, especially during bundle and deployment steps.

  • After setting up port forwarding, from your target device, try:

    curl http://<PC_IP>:5000/v2/_catalog

    to ensure the device can reach your registry.

  • Revisit your .vscode/settings.json or workspace structure if you hit persistent issues:
    Workspace - Structure | Toradex Developer Center

Summary:
Your current approach is valid. To resolve deployment issues, ensure registry ports are shared from WSL 2 to the network—either via the built-in script or manual port proxy setup—so your device can pull images.

If you need further details for a step or run into explicit errors, feel free to provide logs or error messages for more targeted troubleshooting.

Best regards,
Toradex AI Assistant.

3

Greetings @kdubious,

This is strange, so Docker Desktop gets one thing working for you, while Docker Engine gets the other. But neither have both working at once.

Well typically we recommend to install the Docker Engine in WSL itself. We have found Docker Engine in Windows to be troublesome in the past. You said you have “Docker Engine on my Windows PC”, what do you mean by this exactly? The installation is in Windows itself and not WSL?

For reference here’s my setup that works:

  • Windows 10 PC (not sure if it matters compared to Windows 11)
  • Ubuntu 22.04 WSL2 distro from Microsoft itself, so not the Torizon WSL distro.
  • Docker Engine installed directly in this WSL2 distro
    • Windows itself has nothing Docker anything installed. No engine or desktop. Docker is completely within my Ubuntu WSL2.

With this I can use both the VSCode extension and TorizonCore Builder with all of their functionalities just fine.

Perhaps going between the Docker Desktop and Docker Engine has caused a weird configuration on your machine. I know in the past I had Docker Desktop in Windows and uninstalling it, did not actually properly clean up everything configuration-wise.

That’s as much as I can say without knowing anything further or more specific.

Best Regards,
Jeremias

4

Hello @jeremias.tx,

Great news! It works as you described.

I was able to:

  1. Disable the WSL integration in my Windows Docker Desktop. (Flipped the settings switch)
  2. Re-enable my Windows Firewall (I killed this while troubleshooting)
  3. Re-install Docker Engine in WSL (I added the --reinstall flag to the standard Docker installation instructions, and the Docker service came back up immediately)
  4. Reboot my Windows machine (just to be sure that if this works, it survives a reboot)

Then…

  1. I ran a successful tcb build
  2. I was able to debug on the device with the VS Code Extension

I did not install the default Torizon WSL image, which probably would have worked immediately.

I think the “manually install the extension” instructions are not complete. If I have time, I create a clean Ubuntu distro on my WSL, and see if I hit any roadblocks on the path to this setup.

As a side note:

You have been suggesting for (years?) a long time that I live inside of TCB rather than Yocto. The mainstream kernel accommodates my patches now. I’m up and running with TCB requiring just a few minor changes to my kernel module.

Thank you for pointing me to a very simple solution that now works extremely well for my use case.

Kevin

5

Glad I was able to provide assistance.

Best Regards,
Jeremias