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
OS      IMAGE                                               NAME                               ARCHITECTURE  
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
  controllerURI: https://cloud.synpse.net/api
  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

Last updated