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
Install

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
Download
- Raspberry Pi Imager
- CompanionPi Disk Image – The most recent Image is found on the CompanionPi Documents page:
- https://github.com/bitfocus/companion/wiki/CompanionPi-Documentation
- (…having trouble locating it? Download the July 2022 version of CompanionPi directly):
- https://github.com/bitfocus/companion/wiki/CompanionPi-Documentation
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)
- Change the password for the user “Pi”
- S3 Password
- 1 System Options
- 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
- 5 Localisation Options
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:
192.168.8.232:8000
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
Tips
- 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).
What I have found really useful is installing a GUI and Chromium Browser on the same Raspberry PI. Not only does that give me a webpage so I can administer using the same device, but I also use the same device as a remote green screen for H2R graphics.
Yes, I have that exact setup in my rack and run H2R through it. I wanted to keep this first post simple, just to get Companion up and running for people who are new to it, but I might look at a follow-up post down the line. Thanks for the comment!