Companion on a Raspberry Pi 4

When you run Companion on a dedicated piece of hardware like a Raspberry Pi 4, it ensures the central control of your live streaming production is “always on”. Your laptop is freed up to be disconnected/reconnected from the network as needed, and Companion will continue to operate unhindered.

This article will show you how to install a simple “headless” setup of Companion. Headless means the Pi will operate as a server on the network, without a display, keyboard, or mouse. You already have those peripherals on your desktop anyway! So this solution will take up minimal space with low power consumption.

We can then connect a Stream Deck to the Pi via USB for tactile control at your fingertips. And we can still very easily access Companion’s button settings from a laptop web browser, connected to the same router via ethernet or WiFi.


Livestream August 16, 11AM EST



Run CompanionPi with minimal setup: power, Pi, and microSD card.

Hardware Requirements

  • Raspberry Pi 4 (4GB or 8GB) (Optional: protective case)
  • microSD card (32GB or greater capacity. Make sure you get the “A2” rating, such as the 64GB SanDisk Extreme PLUS)
  • 15W USB-C power supply (5v, 3A – example here)
  • Other hardware assumed to be in your setup:
    • A Mac or PC to set up the Pi (in these instructions, I will refer to Mac, but the same can be achieved on PC)
    • A router & ethernet switch



Flash the microSD card

  • Insert the microSD card into your computer.
  • Use Raspberry Pi Imager to “flash” (copy) the entire CompanionPi Disk Image to the microSD card.
    • Operating System > Choose OS > scroll to bottom and select “Use custom” > then select the CompanionPi Disk Image you dowloaded previously
    • Storage > Choose Storage > choose the microSD card you inserted
    • Click “Write”
  • Eject the microSD card from your computer and insert it into your Raspberry Pi 4.

Connect the Raspberry Pi to the Network

  • Insert the flashed microSD card into the Pi
  • Connect the Pi to your router/switch via ethernet cable
  • Connect the Stream Deck to the Pi’s USB3 port (blue inner lining)
  • Connect USB-C power to the Pi
    • The first boot-up will take a bit longer, and the Stream Deck screen will flash a few times
    • The Pi has fully booted up when it displays Companion’s blank “Page 1” buttons

A “headless” CompanionPi, without keyboard or monitor.

Configure the Raspberry Pi Settings via Computer

Use the Terminal Application on a computer that is connected to the same router as the Pi.

Log into the Pi:

ssh pi@companionpi.local

(unless changed, the default password is: raspberry)

Find the Raspberry Pi’s IP Address:

ip r

Make a note of this IP address!

Configure the Pi:

sudo raspi-config

This will open up a graphical settings menu, which is easy to navigate with arrow keys and Enter:

Use the command “ip r” to reveal the Raspbery Pi’s IP Address

  • Set a Secure Password
    • 1 System Options
      • S3 Password
        • Change the password for the user “Pi”
          • <set a secure password>
          • (make a note of this password as you will need to use it next time you ssh back into the Pi)
  • Set the Country
    • 5 Localisation Options
      • L1 Locale – set your location
      • L2 Timezone – set your timezone
      • L3 Keyboard – match your keyboard layout (optional)
      • L4 WLAN Country – set legal wireless channels for your country


Access Companion’s Web Interface

Now that you have CompanionPi up and running, you will access and build your button layouts via your computer that is connected to the same network as the Pi.

Remember the Raspberry Pi’s IP Address you made note of in the previous step? Open a web browser and type that in, and append the port number “8000”.

For instance, mine was:

And that’s it! Enjoy the extensive control of your live productions!


Update CompanionPi

If a new version of Companion becomes available, you can update easily, without having to go through flashing the image process.

Open the Terminal Application on your computer and type the following:

ssh pi@companionpi.local   (hopefully you changed the password by now, otherwise the default password is: raspberry)

Once you have logged into the Pi, type the following command to run the update:

sudo companion-update



  • Make sure the Stream Deck is plugged in before you power on the Pi. If the USB connection is disconnected, cycle the Pi’s power to reboot the Pi, since CompanionPi will search for Stream Decks on startup.
  • Add a button to Companion with the variable text $(internal:all_ip) to show all IP addresses available. That way, if you ever move the CompanionPi to a different network (ie between the studio and a location shoot), you will be able to see at a glance what IP address has been assigned to the Pi on the new network, without having to connect a laptop to ssh in to check.
  • Once you have CompanionPi up and running on your network, use Companion Satellite to connect a Stream Deck to any other computer. That way you can maintain a single Companion installation from a distance.
    • For instance, say you have CompanionPi running permanently in a rack. Then you connect your laptop over Wifi, and a Stream Deck to that laptop. Using Companion Satellite, you’ll enter CompanionPi’s IP Address to operate your production remotely (because you like coffee breaks from the outdoor sofa).