Headless (Ubuntu)

Headless install allows to create single SD card and replicate it to multiple devices, without a need to manually configure the devices. This is great when you don't have a spare monitor!


  • Linux based machine (WSL on Windows or MacOS does not work)
  • Synpse CLI installed and logged in to Synpse Cloud
  • sudo permissions as synpse build command uses mount to prepare the image
  • SD card burner such as Etcher or Raspberry Pi Imager

Getting started

Chose the base image you want to use for your build. If you don't find the base images you would like, let us know in Discord to see what we can do about this!
synpse machine-images list-base
ubuntu ubuntu-20.04.2-preinstalled-server-arm64+raspi.img Ubuntu Server 20.04.2 LTS (ARM64) arm64
ubuntu ubuntu-20.04.2-preinstalled-server-armhf+raspi.img Ubuntu Server 20.04.2 LTS (ARM32) arm32
Run build command with build parameters:
sudo synpse build \
--hostname "synpse-edge" \
--image ubuntu-20.04.2-preinstalled-server-arm64+raspi.img \
--image-output $(pwd)/images \
--wifi-name WIFI_SSID_NAME \
--wifi-password $WIFI_PASSWORD
This will output the image into images/ directory. Now, use either Etcher or Raspberry Pi Imager to burn this image into an SD card.
If --project-id or--registration-token is not provided CLI attempt to get default provisioning token for the project configured in CLI.
After building the image startup might take 10-15 minutes for updates and install of the latest binaries. Time might wary based on your internet speed.

Build using config file

You can also build an image using configuration file
synpse build --config-file config.yaml
Where config.yaml is an example bellow:
image: ubuntu-20.04.2-preinstalled-server-arm64+raspi.img
outputDir: /home/user/images
projectID: prj_1qtJj73NFMHm0QoRj2uPWxxxxxx
registrationToken: drt_1qtJj55aIhGiMrXs5BDAvxxxxx
hostname: synpse-edge
unixUser: synpse
sshKey: ssh-rsa ABCD
#locale: en_US.UTF-8
#timezone: Europe/Vilnius
- wifiAccessPointName: WIFI_SSID
wifiAccessPointPassword: Wifi_Password