Skip to main content

Linux Native Application

The device software can also run on a native Linux machine thanks to the Portduino framework.

The application either simulates some of the interfaces, or uses the real hardware of your machine. Device firmware from 1.3.42 and on even allows you to simulate the LoRa chip by sending and receiving Meshtastic packets via a local TCP port. In this way, you can let multiple instances of the application communicate with each other as if they did via LoRa. For instructions on how to use it, see the interactive simulator that also emulates a wireless environment using simulated positions of the nodes.

Usage with a Linux machine

The easiest way of building the native application is using Visual Studio Code with the PlatformIO extension. See the instructions for creating such a building environment here.

Then after opening the firmware repository in Visual Studio Code, simply click on the PlatformIO extension in the left bar, select native and click on 'Build'. This will generate the binary file 'program' which you can find in .pio/build/native/. Once in this directory or when you copied the file to your current directory, launch the application with ./program.

Additional arguments can be given to the program, which are listed as follows:

  • -d DIRECTORY: The directory to use as the virtual filesystem (VFS).
  • -e: Erase the virtual filesystem before use.
  • -h MAC_ADDRESS: The MAC address to assign to this virtual machine.
  • -p TCP_PORT: The local TCP port to use for running the Meshtastic API.

Usage with Docker

If you do not own a Linux machine, or you just want to separate things, you might want to run the application inside a docker container.

The Image

To build docker image, type

docker build -t meshtastic/device .


To run a container, type

docker run --rm -p 4403:4403 meshtastic/device

or, to get an interactive shell on the docker created container:

docker run -it -p 4403:4403 meshtastic/device bash

You might want to mount your local development folder: firmware docker run -it --mount type=bind,source=/PathToMyProjects/Meshtastic/Meshtastic-device-mybranch,target=/Meshtastic-device-mybranch -p 4403:4403 meshtastic/device bash

Build the native application

Linux native application should be built inside the container. For this you must run container with interactive console "-it", as seen above.

First, some environment variables need to be set up with command:

. ~/.platformio/penv/bin/activate

You can build amd64 image with command


Executing the application interactively

The built binary file should be found under name release/latest/bins/universal/meshtastic_linux_amd64. If this is not the case, you can also use the direct program name: .pio/build/native/program

To use Python CLI against exposed TCP port 4403, type this in the host machine:

meshtastic --info --host localhost

While you can interact with it in the same way as a normal device using a client that supports TCP connections, the application has its limitations. For example, rebooting is not implemented, so for some settings to apply you have to restart the application.

Stop the container

Run this to get the ID:

docker ps

Stop the container with command:

docker kill <id>

Tip: you can just use the first few characters of the ID in docker commands