meshtastic/docs/software/linux-native.mdx

---
id: linux-native
title: Linux Native Application
sidebar_label: Linux Native
sidebar_position: 5
---

The device software can also run on a native Linux machine thanks to the [Portduino framework](https://github.com/geeksville/framework-portduino).

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](https://github.com/GUVWAF/Meshtasticator/blob/master/INTERACTIVE_SIM.md) 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](/docs/development/firmware/build).

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 .`

### Usage

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 also want to make some adjustments in the bin/build-all.sh to conform the amd64 build:

```shell
  sed -i 's/^BOARDS_ESP32.*/BOARDS_ESP32=""/' bin/build-all.sh
  sed -i 's/^BOARDS_NRF52.*/BOARDS_NRF52=""/' bin/build-all.sh
  sed -i 's/echo "Building SPIFFS.*/exit/' bin/build-all.sh
```

You can build amd64 image with command

`bin/build-all.sh`

### 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