Set up a bitcoin node with Umbrel, the hard way


Disclosure: As I continue to tinker with my setup and go through my commands again I have discovered a number of mistakes, particularly with my attention to folder structure when troubleshooting the X735. Please do your own research and understand that I am still learning.

Bitcoin vs. bitcoin

Before we dive in, I want to recognize the difference between Bitcoin and bitcoin. I’m certainly going to make mistakes throughout this writing but I’ll do my best. Bitcoin, capitalized, is the cryptocurrency — bitcoin, not capitalized, is the protocol. Individuals interact with bitcoin to send each other Bitcoin.

I hope that by recognizing that I am aware of the difference, the maxis will leave me alone. Now onto the post where I proceed to botch the proper capitalization of Bitcoin and bitcoin.

Running a Full Node

Umbrel has a smooth pitch. Take one look at their website and you can’t wait to set up a bitcoin node. Why “buy bitcoin” when you can “become bitcoin” ?!

Initially when I explained to family or friends that I was interested in setting up a bitcoin node, they thought I would be turning a profit. Folks are more familiar with mining Bitcoin than they are with supporting a bitcoin node.

I took a small dive into the difference and landed on the square and rectangle situation. All miners are nodes, but not all nodes are miners. Running a node means that you are providing support to the network in the form of information security. You are not competing to verify transactions and being rewarded in the form of Bitcoin, you are simply hosting and sharing a copy of the bitcoin blockchain. As long as there is always one node with a history of the chain, the Bitcoin transaction history is intact and other nodes can re-sync the transaction history.

A good friend of mine asked if I am essentially doing community service. I suppose that by providing support to the network, running a node is providing a service to the community. Though there are some selfish reasons to run a node as well. When you run your own node, you can connect your wallet and route transactions through your node ensuring that no nefarious actions are occurring with regard to your transactions.

I also ran into a discussion around running a full node or a partial node. I didn’t spend much time looking into this distinction once I realized that a full node was better as it maintained a comprehensive history of all transactions. Let’s do it the right way, in excess, with no pruning.

From what I’ve read and seen, Umbrel makes it dead simple to set up a bitcoin node. So simple (writing this before I set up Umbrel, so hopefully I don’t have to eat my words), that I wanted to create an extra challenge for myself somehow.

Take a look at their site… they make it look incredibly easy, too easy…

Setting Up a Node

Umbrel includes a list to parts on their site to get started with a Raspberry Pi 4. Awesome, I’ve used a Pi 3 in the past and it’s collecting dust right now. It would be good to put it back to work.

Let’s take a look at the full list:

Raspberry Pi 4
SSD Enclosure
16GB+ microSD
Power Supply
Ethernet Cable

Let’ s take a look at that list again trying to save money:

Raspberry Pi 4 (I have a Raspberry Pi 3)
1TB SSD (I’m sure I have a hard drive sitting around, probably not solid-state)
SSD Enclosure (Do I have to? I feel lazy)
16GB+ microSD (Just found an 8GB one, let’s try that)
Power Supply (I have a Raspberry Pi 3)
Ethernet Cable (Do I have to? My router is not in a good place for another device)
Case (I have a Raspberry Pi 3)

Awesome, I will set up a node for free using materials I have. Challenge accepted.

Back to the list.

All items listed are reasonable and the only expensive pieces are the Raspberry Pi 4 and the SSD, both items that will retain value for future projects if things don’t go as smoothly as the Umbrel website and Twitter feed make it seem.

We’re talking ~$250 USD to get going. As always, when I start throwing money around in the name of crypto, I’ll frame it as a learning cost. A couple hundred bucks is worth it to learn more about how bitcoin actually works and if this lightning thing I’ve been hearing about since 2017 is worth anything.

A friend of mine who runs a node on Umbrel mentioned something about setting up a lightning channel between each other. Who knows. Hopefully I understand what that means more by the time everything is set up and operational. For now, let’s ape.

Node Build Examples

When you look at @getumbrel’s Twitter feed you see plenty of builds.

It’s honestly really impressive how many people seem to be setting up nodes using Umbrel. There are plenty of guides and walk through videos on YouTube. Again, take a look at their site. Design matters and Umbrel’s built a slick on-ramp to a beautiful interface.

Call me snobby or a jerk but the somewhat messy look of these systems frustrated me. Most of these are using the exact links from the list that Umbrel provides. Some of the items on the list are even sold out at the time of writing this. Again, the on-ramp is impressive. Umbrel has clearly captured others’ interests as well as mine.

The largest pieces required when setting up the node are the Raspberry Pi 4 and the SSD. Umbrel suggests buying separate cases for each and connecting them via USB. This is the most economic choice but what you save in material costs you pay for in appearance.

I do not mean to be an asshole. By creating a node, @niteshbalusu11 is doing a good, important thing. I am only including his post because it was one of the first ones I saw when scrolling the Umbrel Twitter feed looking for an example and I am jealous that he has enough space to leave a full bitcoin node on the floor. My apartment is not that forgiving (we’ll come back to this).

Posts like the below, however, started to get the gears in my head turning. Could I find an enclosure that would contain all of the pieces?

The SSD is still sitting to the side!

I haven’t built a computer in over 10 years but I knew there must be a vendor that could provide the parts needed to enclose the entire build. The last time I ordered a Pi, I was shocked by the amount of aftermarket accessories that were available. Expansion boards, touchscreens, sensor kits, you name it.

All I wanted was a case that could hold the Pi and the SSD.

Enclosure Options

Turns out that you can’t go on Amazon and search “Raspberry Pi 4 SSD enclosure” or “Raspberry Pi 4 SSD case” and then click Add to Cart.

There are a couple items that come up immediately. Offerings from Geekworm and Argon. Both of these seem to do what I am looking for.

Geekworm Raspberry Pi 4 X825-C6
Argon ONE M.2 Case for Raspberry Pi 4

The Argon case uses a different SSD form factor than I am familiar with, and again the appearance is not doing it for me.

External USB Bridge from SSD to Raspberry Pi

The overall form factor of the Argon is quite small and honestly, it’s probably better looking than the Geekworm box.

The Argon box works with a M.2 SATA SSD with B-Key or B+M Key. This SSD form factor is new to me, I did not want to do this research just to have a Star Trek looking bitcoin node. I liked the look of the Geekworm option enough. It’s kind of fugly, but it doesn’t try to be more than it is. It’s a metal case for some computer boards and it reminded me of the Hackintosh I shoved into a simple, black computer case in 2010.

Beyond appearances, I noticed that going the Geekworm route included using some expansion boards to get everything working together.

Now we’re talking

Here was my challenge. For those that mess with hardware often, this is likely a walk in the park. But I don’t get to play with hardware ever and I’ve always been fascinated by the stacked board projects I’ve seen others complete.

I am always excited to use my hands to put something together and this struck me as the perfect opportunity.

After watching some videos of construction and doing some reading on compatibility between the various boards and cases I got my Amazon cart together.

The Final List

Amazon Order

In the end I swung polar opposite from using what I had laying around the house and threw down the cash. Well, actually my parents had some leftover Amazon credit and were kind enough to sponsor this build, thanks Mom.

What we’re working with:

Raspberry Pi 4
Geekworm X825 V2.0 SSD Expansion Board
Geekworm X735 V2.5 Power Management Expansion Board
32GB microSD
Power Supply
Geekworm X825-C8 Case

Notice we omitted the ethernet cable. I really don’t want to plug this thing in to my router.

What’s the deal with the apartment and the router?

Not great, Bob

No one wants to splatter their bitcoin node with bacon grease. I hate doing it to my modem and router, but there is only so much I can control in that space. That is the only coax connection available in the apartment and the unit is not hardwired with any other ethernet connections.

Honestly, this was a hang up stopping me from starting this project. I did not want to add more clutter to the window sill in the kitchen and I did not want to subject the node to potential cooking mishaps.

From here I saw a couple of potential paths forward. I could set up a wifi extender that had ethernet ports and plug it into that or I could look further into the wifi capabilities of the Raspberry Pi 4.

The wifi extender route was expensive, conceptually unnecessary in a space as small as the apartment, and could potentially contribute more interference to the existing network.

As the Raspberry Pi 4 supports wifi, I was hoping there was a work around.

And there was Umbrel, making it easy again.

Building Prep

I love video tutorials. Naturally, I searched around on YouTube and found an official video from Geekworm showing how to put this kit together.

After watching this video multiple times, including rewinding specific pieces, I completely lost my mind. As the comments point out, this song can drive you mad.

Same. Though I choose not to mute. Why?

Moving past the deep debate around the music… this video has one other factor that is less than ideal. It shows how to perform multiple builds and therefore includes building without the X735 and then tearing down to add the X735. Basically, if I were to follow this video straight through I would build it one way, then take it apart to build it in totality. It has some helpful informational captions but I took another look to see if I could find a more straightforward video.

This brought me to a video by PE4Doers.

This video moves much more methodically, the builder talks through what he doing and he follows the build straight through without doing a partial that requires re-work. The small tips and tricks are helpful as well — it’s helpful to know the common pitfalls and operate with them in mind.

I noticed that this was the second video in a series so I took a look at the previous video. YouTube can be such a rabbit hole. I like this guy’s channel. He deserves more views, pump the numbers!

Prior to finding the video from PE4Doers, I was trying to diagram out the connections based on the video from Geekworm.

Connections between hardware pieces

We can see that this is actually extremely straightforward from a construction standpoint. Our SSD will plug in to the X825 board via a SATA connection. The X825 will connect to the Raspberry Pi 4 with a USB bridge. The X735 board will sit on top of the Raspberry Pi using the 40 pin connector. We’ll use a connection from the X735 to the X825 to supply power to the SSD. A dedicated power button is connected to the X735.

Again, I want to thank David Rivera for making it clear how simple this specific build. I still can’t get the music from the Geekworm video out of my head.

Software Set Up

This probably doesn’t even need a section. I followed the instructions on the Umbrel website and downloaded Umbrel OS and Balena Etcher. I then used Balena Etcher to flash the Umbrel OS disk image to the microSD card.


My order included a USB to SD card adapter purely for this purpose. In the future I will need to find another project for that obsolete Raspberry Pi 3 and get more use out of the converter. I’m certainly not using it for photos.

Let’s Build…

Again, thanks Mom!

I started out by getting the OS flashed to the microSD and adding the wpa_supplicant.conf file with my wireless network information. I doubt that this will be as simple as I made it out to be, we’ll see if we need to come back and troubleshoot this piece.

After that I applied the heat sinks to the Raspberry Pi 4.

Got to stay cool

Optimizing the Hardware

Before we continue I want to ensure that all parts are operating correctly.

The X735 power management board includes a safe shutdown feature. Since this is a bitcoin node, we’ll want it to be running 24/7 but it seems to make sense to set up the safe shutdown so that we can turn the node off and move it as needed.

Again I looked for videos and found this helpful video from GigaBauer Tech, though I am not sure which version of the X735 is being used.

I have the X735 V2.5 and after Googling I found the below information from Geekworm discussing the script needed to enable the safe shutdown feature.

X735 V2.5 Software

Looking at Amazon reviews I also see some concerning posts about the X735 frying some Raspberry Pis. Let’s hope that does not happen here.

Let’s hope for a better experience than this…

I’ve also noticed repeated clarification to not provide power to the Pi from multiple sources. Power should be supplied to the X735 which then manages power output to the Pi via the 40 pin connector and to the X825.

Candidly, I am operating out of my area of expertise. Please excuse the fact that I am figuring this out as I work through it!

Based on what I’ve seen we should not expect the fan to work whatsoever without the script installed.

I knew that this project would require some troubleshooting and I am starting to feel that come to fruition.

As I am trying to understand how to get the X735 safe shutdown script working I think back to the initial Geekworm video as well as the video from GigaBauer Tech. In both cases, the machine is built using the Pi, SSD, and X825. After getting the initial build completed, the X735 is being added.

While I initially wanted to do the full build I am now considering completing the partial and then returning to add the power management board.

After plugging power into the Raspberry Pi and viewing devices connected to my network via the router dashboard I do not see the Pi.

I need to get the IP address of the device to SSH in and install the safe shutdown script.

After plugging the Pi into the router via ethernet, I was able to identify the device on the dashboard.

This is untenable and why we need to get the wifi configuration working

At this point, I wonder if I incorrectly added the wifi configuration file. Upon reviewing the microSD, I do not see the file… that certainly could be the issue.

After reviewing the file I previously added, I notice that I also forgot to add my country code. As I mentioned, this is all new to me so bear with me and expect a lot of troubleshooting from here on in. Buying boards is easy, getting them to do what you want takes a bit more work.

That did the trick. I am now finding the Raspberry Pi on my network without using ethernet!

Now let’s get crazy and try to add the safe shutdown script via SSH.

I was able to SSH into the device using:

$ ssh umbrel@umbrel.local

Looking inside I see the file structure within umbrel

When reviewing the other material related to installing the X735 safe shutdown script I see that I need to access .config .

I can’t seem to access that so I take a look at scripts .

I am unable to cd intoconfigure …

At this point I will just start trying things. Worst case, we re-flash Umbrel OS to the microSD card and start fresh.

$ cd ..
$ sudo apt-get update
$ sudo apt-get install python-smbus
$ sudo apt-get install pigpio python-pigpio python3-pigpio

Downloading the script…

$ git clone

Setting up the script…

$ cd x735-v2.5
$ sudo chmod +x
$ sudo bash
$ printf "%s\n" "alias x735off='sudo'" >> ~/.bashrc


$ sudo reboot

At this point, the instructions suggest testing the safe shutdown and monitoring the fan. Well, we don’t have the X735 attached yet!

We’ll come back to the X735.

Back to Building…

After removing all of my parts, I immediately notice that I am missing the power cable to connect the X825 to the X735.

Upon reviewing the Geekworm documentation, I find that this cable is no longer needed due to the test pins added to power the board from the Pi without need for another cable.

X825 V2.0

Okay, I’ll take their word for it!

X825 + Raspberry Pi 4

I wanted to test things out without the X735 before getting the safe shutdown script installed.

After getting power to this contraption, however, I lost the ability to SSH in or to find the IP address via my router’s dashboard. I had expected to essentially have a fully operational node at this point, but alas, that would be too easy.

Time to power down and check the wpa_supplicant.conf file again.

And it’s gone again. This appears to be an issue that others run into.

There is some discussion around how to persist this file.

This post suggests that the microSD needs to be re-flashed as the unplugging that I am doing is corrupting the card.

How do I keep Umbrel from disconnecting after a period of inactivity

For now, I’m going to be lazy and simply re-add the file. I fully expect I will need to re-flash and re-create the file again but for now I am still working to get an initial build working.

Success. Adding the file again now allows me to see the Pi on my network.

Well, maybe not. After a short period of time the device disappears from my client list. I am also unable to access umbrel.local or navigate to the interface via the IP address.

Let’s re-flash.

After re-flashing, re-adding wpa_supplicant.conf , and rebooting the Pi is once again visible on the client list.

Accessing umbrel.local or attempting to navigate to the IP address, however, leads nowhere.

Apparently after re-flashing the OS, my previously added known host did not agree with the new instance. Again, out of my element here so I will spare you from going into any depth there. We’re in deep troubleshooting mode but I am sure we can make this work!

The amount of troubleshooting that has been performed is not even worth sharing.

At this point the entire build has been deconstructed and reconstructed multiple times. I have tried flashing a previous version of Umbrel OS to the microSD card. I have tried powering the device via the Pi, the X825, and the X735 all in different partial builds.

I have added and removed the wifi configuration as well as totally removing the safe shutdown script for the time being.

I have done more networking (no, not the kind that gets you a job) today than I have done in the past 10 years.

I have pulled the error logs using $ ~/umbrel/scripts/debug --upload many times. I have reached out to the community in Telegram and Discord sharing these error logs as well as my hardware stack and variations of the same.

Unfortunately, these spaces are nowhere near as communicative as some of the other Discords I participate in. I have hope that others will be able to help, but I am discouraged by the lack of engagement from the community. I suppose a device like this is closer to set it and forget it so it makes sense that the communities are low engagement.

Error logs from others lead to messages to only use the suggested hardware.

Fine, I’ve now ordered the “official” Raspberry Pi 4 power supply as well as an SSD enclosure.

Pouring money on the node build

I previously mentioned not wanting to talk more about dealing with the known hosts file. At this point I have run $ rm -f .ssh/known_hosts more than anyone should ever be comfortable with. Thankfully, as I mentioned, I do not often deal with networked hardware so the only connection stored there is this one.

What Gives?

I wanted to make this harder for myself and I did.

I’m back at X825 + Raspberry Pi + SSD + 5V DC power supply through the X825. When I run an error report the SSD is not found and I get multiple errors. the indicator light on the X825 shows no activity on the SSD so I should not be surprised that the Pi fails to recognize the SSD.

Well. I forgot to include the USB bridge. Honestly, putting this in writing is borderline embarrassing.

I should stick to spreadsheets and mind maps because I am clearly out of my element.

Bridge has been added back, power through the X825… let’s run that error log again…

I continue to receive the error that I had earlier in various other build stacks.

The issue appears to be related to a missing or improperly configured docker file…?

Part of me wants to complete a full build with this hardware using a different OS to prove to myself that there is no issue with the hardware. I could go for a simple Raspbian OS install to be sure that the hardware makes sense.


After reaching out on Twitter, I finally got assistance on my docker issue from Luke Childs at 3am my time.

The code that worked for me was a bit different and Luke actually deleted the tweet containing the proper code before sending the above one.

(I have no real idea what this code does beyond inferring that we are pruning the docker packages and restarting the Umbrel system, but I am including here in case it is useful for anyone else)

Crypto never sleeps

I let the node run its sync overnight and woke up to ~20% progress.

Syncing over wifi!

This feels close to complete. I have gotten comfortable with re-flashing the OS and re-adding the wifi configuration file. I am happy to see that this is working over wifi and at a speed that is acceptable. At this rate, I would expect to sync the entire bitcoin blockchain in ~3–4 days over wifi. That’s slower than the speeds that others are getting via ethernet but acceptable to me because I don’t need to leave the Pi next to the oven.

I like Pies and Ovens (shout out PieDAO), but that’s a story for a different day.

The last step before getting the node into its case will be to get the script for the X735 operational. We could take the X735 out of the equation and use the fan included with the case but it would be great to get the power management board with a temperature controlled working.

Feeling hot, hot, hot

I’ve seen the temperature go into the 70s. I’ve combatted this by leaving the node in front of an air conditioning unit and seen the temperature drop into the 40s.

Is this really better than the kitchen? No.

Time to circle back to the safe shutdown script.

X735 and Safe Shutdown Script

X735 V2.5 Software

I have concerns that getting this working on Umbrel OS will not be as simple as laid out in the instructions from Geekworm. But we’ll give it a shot. I can always remove the directories I add and worst case can re-flash the OS. I’ve noticed by this point that re-flashing the OS does not really change much. I can still log into Umbrel with the same credentials and the blockchain progress starts again where it left off.

Strangely, whenever I power the Pi down with the button on the X735 I need to re-flash the OS and re-add the wifi configuration file but I have not had to deal with the docker issues after addressing them on previous instance of the OS… maybe that information is persisting on the SSD? I would appreciate knowing more about this from someone smarter than me.

By the way, shutting down the Pi over SSH using $ sudo shutdown -h now keeps the OS and the wifi configuration file intact.

And using $ ssh-keygen -R umbrel.local is a better, safer way to reset the known hosts file (I think). But ask your IT professional what the best way is.

What about when you are the system administrator…?

Following the instructions to step 5 in the Geekworm script documentation worked. I was able to perform a shutdown using $ x735off . Though, when I did this I had to re-add the wifi configuration file again. I think that we’ll need to circle back and find a way to persist that file.

Using $ python /home/pi/x735-v2.5/ did nothing for me.

$ python3 /home/pi/x735-v2.5/ did not work either.

My file structure is a bit different so I tried $ python3 x735-v2.5/ but I received an error:

Traceback (most recent call last):
File "x735-v2.5/", line 2, in <module>
import RPi.GPIO as GPIO
ModuleNotFoundError: No module named 'RPi'

This Stack Overflow article provided a line to install RPi.

sudo apt-get -y install python3-rpi.gpio

After running this I was able to successfully start the fan! We’re getting close.

While performing these actions, I am also monitoring the Umbrel dashboard and seeing a continuous synchronization. That tells me that adding these functions is not interfering with Umbrel.

Temps are looking better, hanging around 50. I’ll be interested to see if the case provides a better air flow that results in lower temperatures.

The Geekworm documentation notes that we want to get the script to run at startup, not upon manual execution.

umbrel@umbrel:~ $ sudo crontab -e
[sudo] password for umbrel:
no crontab for root - using an empty one
Select an editor.  To change later, run 'select-editor'.
1. /bin/nano        <---- easiest
2. /usr/bin/vim.tiny
Choose 1-2 [1]:

I selected 1 to use nano and added the following line at the bottom of the file:

@reboot python3 x735-v2.5/

After running a shutdown command and turning the device back on, the fan does not run. Running the script manually, however, still works.

The edits I made to the crontab file did not persist, so it makes sense that the fan did not start at boot.

Re-edit crontab. Save. Run $ x735off …

Press the button on the X735 to boot up… pray… and the fan is running!

I did not expect that to work.

The real test will be if I can use the button to turn it off. That’s what we’re going for here. I don’t want to have to SSH in and shut the node down remotely.

The X735 documentation says to press and hold the button for 3~7 seconds to perform the safe shutdown. That seemed to work for me.

Pressing the onboard button to turn the machine back on runs the fan. Using the external momentary button also works. Fingers crossed that we are done with the fan piece.

Enclosing the Node

If you made it this far and you read through the troubleshooting you might be even stranger than me. I respect that.

If you remember, I started down this path to build a bitcoin node using Umbrel but with the goal of creating a build that appeared more professional from the outside.

Geekworm provides a case and a set of expansion boards that allow the SSD to be enclosed together with with the Raspberry Pi.

Getting everything to work together proved to be a challenge, but that made it that much more fulfilling to get the whole thing operational.

I struggled to get everything into the Geekworm case, so I used pair of pliers to pull the tabs away from the opening.

I was then able to slide the build into the case, use the pliers to push the tabs back, and get the other half of the closure attached.

And we’re done.

What’s Next?

Now that Umbrel is syncing down the history of the bitcoin blockchain it’s time to catch my breath before diving in to understand what types of apps are available, what type of wallet software I might want to integrate, and to continue researching how I can use the Umbrel interface to continue to “become bitcoin”.

Set up a bitcoin node with Umbrel, the hard way was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.