PlatformIO Community

HowTo: Raspberry Pi 3 as remote agent (Oct. 2020)

I finally managed to set up a raspberry pi 3 as a remote agent. Since I had some difficulty on the road, I’ll share my setup script here to help others with this setup.


  • I’m using a system wide installation of platformio instead of the virtualenv installation, because a) it’s the only way I could get it to work and b) I’m not using the raspi for anything else.
  • Some of the insallation steps can take quite a while on the raspi, be patient!


  1. Raspberry Pi 3
  2. SD card with at least 4GB space (2GB is not enough)
  3. rpi-imager installed


  1. Use rpi-imager to prepare the sd card
  • Select “Raspberry Pi OS (32-bit) Lite”
  • This guide was created using Version: August 2020
  1. Mount the sd card and open the boot partition
  2. Setup wifi (if needed)
  • in the boot partition, create ẁpa_supplicant.conf file with the wlan config:
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
country=<Insert 2 letter ISO 3166-1 country code here>

 ssid="<Name of your wireless LAN>"
 psk="<Password for your wireless LAN>"
  1. In the boot partition, create an empty file called ssh to enable ssh on boot.
  2. Insert the card into the raspberry pi and connect the power. The raspi will boot up and do the initial setup.
  3. Connect via ssh
ssh pi@raspberrypi
  • the initial password is raspberry
  1. Set a new password
  1. Install platformio
# update system
sudo apt update
sudo apt upgrade -y

# install required packages
sudo apt install python3-pip libffi-dev libssl-dev

# install platformio
sudo pip3 install platformio

# install required libraries for the remote agent
pio remote agent
  1. Get the platformio auth token (you can do this on any computer)
# login to platformio
pio account login
# get the auth token
pio account token
  • save the token for the next step
  1. Install the remote agent as a service
  • create a file /etc/systemd/system/pio-remote.service:
Description=pio remote agent

Environment="PLATFORMIO_AUTH_TOKEN=<insert your auth token from last step>"
ExecStart=/usr/local/bin/platformio remote agent start

  1. Start the service
sudo systemctl start pio-remote
  1. Check that the service is running
systemctl status pio-remote
  • In case of errors, check the error log
journalctl -e -t platformio

The service should be running and you can access the remote agent from any platformio installation by logging in to your account.

Let me know if you have any questions or issues regarding this guide.


Thanks for that tutorial, helped me to install the remote agents without errors.
Great tutorial, just one misspelling here “sudo apt install pyhton3-pip libffi-dev libssl-dev” should be “python3-pip” :frowning:

Oh, right, thanks!
I actually have to fix that in my script :sweat_smile:
Fixed in the post.

1 Like

no Problem, but perhaps can you help me, Starting the service following your tutorial, I get errors. Just did cut an paste from your tutorial and added the key I generated.

● pio-remote.service - pio remote agent
   Loaded: error (Reason: Unit pio-remote.service failed to load properly: Invalid argument.)
   Active: inactive (dead)

Oct 24 16:40:57 CAN-B systemd[1]: /etc/systemd/system/pio-remote.service:9: Invalid environment assignment, ignoring: PLATFORMIO_AUTH_T
Oct 24 16:40:57 CAN-B systemd[1]: /etc/systemd/system/pio-remote.service:15: Missing '='.
Oct 24 16:41:09 CAN-B systemd[1]: /etc/systemd/system/pio-remote.service:9: Invalid environment assignment, ignoring: PLATFORMIO_AUTH_T
Oct 24 16:41:09 CAN-B systemd[1]: /etc/systemd/system/pio-remote.service:15: Missing '='.

Service config

Description=pio remote agent

Environment="PLATFORMIO_AUTH_TOKEN mq2[censored]"
ExecStart=/usr/local/bin/platformio remote agent start


Thanks for Help Rainer

Missing ‘=’ perhaps? Try:


From the above:


Yes thanks, but f* there was a second problem, a single double quote in the last line. Removing ist fixed it,

Thanks again Rainer

Solved, there was a douple quote in the last line, I removes it.

Thanks Rainer

How do I adjust my platformio.ini so that the build is automatically happening on my remote Raspberry Pi?

Not sure about the platformio.ini but does this help? – that’s what process I followed.


Mhm, remote development via SSH is not really what I want. I want to work locally and build all platforms, not only the Pi but also other ones. The Pi platform has to be built remote, the other ones can be built locally.

1 Like

As far as I know there is no platformio.ini configuration for that – you must either pio remote run on the CLI or use the “Remote” tasks in VSCode.

Feature requests can be filed at

Ah, okay. Thank you! I misunderstood the docs first, did setup a PR for clarification: