Published in


The definitive guide to Secure Scuttlebutt

An “offline first” P2P protocol

1- Common problems I would like to solve

I have noticed that I am a constantly and extremely dissatisfied computer user. There is a lot of things I would like to be possible (and easy) but which, these days, are kind of dead end cases. These are common problems I believe afflict many people, not just me. And I feel a bit frustrated at not being able to solve them, either because of lack of time or because of lack of capacity, even …

1.1- Two laptops

I use two distinct laptops: one at home and one at work. And I’d like my “archives” (the things I save in HD that are reasonably well organized and cataloged) to be perfectly synchronized between the two. That is: changes I make in one I want them to be applied also to another and vice versa.

But every time I leave the office, I leave that laptop to sleep. And it is going to be about an hour until I wake up the laptop from home. I absolutely would not want to arrange a “uptime overlap” between the two, nor to “mirror” my stuff on a third machine — see, I have over 62GB of files in my archives.

And, behold, most of these 62GB are already on both machines. All I need to do is synchronize a few changes, usually something like a few mebibytes each time (like when I download the pictures from the phone into the laptop).

And, no, Dropbox is absolutely not a solution. Damn, how I suffer from his excessive I/O with just over 2GiB! Imagine 62! And I do not want to “trust” closed code. I even run Dropbox on Firejail , but it still has access to a lot of data that should be kept confidential — and they end up being at the mercy of the Dropbox “troupe” goodwill.

And if there is something I have learned binge watching X-Files is:

Trust no one!

And now, how to proceed?

1.2- File system

I can even get organized with the file system — I’m a shell guy — but I need to make choices. And, “at every choice, a loss”. For instance, I organize my photos per year . Then there is a directory for each year: 2008, 2009, 2010 and so on. But if I want to see all the photos in which my dog appears, well … the things get complicated a little. I would need to make use of those applications that generate albums. But I hate them. The ideal, for me, would be to do this:

# ristretto /mnt/archives/photos/all-photos-with-my-dog

(“ristretto” is the image viewing application I use.)

1.3- The pictures that my mother takes

This was the “use case” that led me to “SSB”: my mother has a tablet for a long time and takes many pictures with it. And not just photos: there are a lot of videos, too. I'm impressed with the fact that its storage space is not depleted, yet…

And, you see, my parents went to live in the woods . Connectivity? Ha! You can barely talk on the phone…

I also have my own photos here and would like to exchange them with my parents. But when we meet, no one is interested in the tedious process of looking at each photo and deciding what goes there and what comes here. This is the kind of thing that must be done right after the capture: “took the photo, shared it and that’s it.

What I think would be nice: that my parents had a “local Facebook”, that works even without an internet connection as we know it. My mom takes a picture and shares it. Both (my father and her) have access to the photograph. Eventually, my father comes at my house to pick up the mail (because if the Post Office does not work right here in the capital, think about what it’s like in the woods!) and connects his cell phone to my wi-fi router. Now my laptop also has access to the photos too!

And this process does not have to be complete or fast: it’s okay if my father is in a hurry and, of the 100 photos, I can only see 30. I can get the rest another day. All right, too, if I make a comment on one of them and my mother will only see it in a week. We are not in a hurry about it.

And, what’s better: I do not want to interact with the system. Let it synchronize himself.

2- Enter Secure Scuttlebutt

Secure Scuttlebutt (SSB) is a protocol that provides standards for defining identities and managing information feeds. Of course, it does not solve all the problems I mentioned. But it certainly solves some of them.

2.1- A protocol based on gossip

Do you know when you’re going to get some water, find that guy from the other department and ask how you guys going there? At the time of filling the bottle you discover that the daughter of Mrs. Tereza is pregnant with her third child, that Theodore quit to work for the competitor and that Caetano, who was supposed to go in his place, was left behind because the boss thought Cardoso was much more competent. This is one of the definitions of “scuttlebutt” (which was originally a version of “the water bottle” from ships —can you picture how the term evolved?).

In a way, it’s the opposite of what ZeroNet is . ZeroNet would be you with five phones all turned on, knowing everything that happens in the company all the time, real time. The SSB is about updating yourself between getting up from your table to get a coffee and going back.

(About the term “scuttlebutt”, see also: )

2.2- Offline first

Do you know the movement/concept/school “offline first“? See . The idea is that you should always create your applications considering that they should work well even if the device on which they run is absolutely offline. And this is not something to be applied only to “developing countries”:

Frequently not having any data connection in even the wealthiest and most developed cities of the world has led us to conclude that, the mobile connectivity / bandwidth issue is not just going to solve itself at a global level anywhere in the near future.

The focus of SSB, then, is not on speed but, in a sense, on consistency: we will not always be all connected, but in the long run, connecting from time to time, everyone tends to keep up to date on everyone.

2.3- A protocol based on social interactions

In that quick chat that happened when fetching some water you received updates on the daughter of Mrs. Tereza, about Theodore, about Caetano, about the Boss and Cardoso. And you do not even know Cardoso! But if anyone asks you about him, now you can: “ I do not know him, but I learned that he was promoted — he's now in Theodore’s previous position.”

SSB works on similar premises. You’ll keep in your machine, in addition to your own data, updates on the people you follow — and on the people who are followed by whom you follow.

(This is the default implementation, of course. But from what I understand about the protocol, nothing prevents you from creating a client that allows you to set space limits for “seconds” and “third parties.”)

Plus, by meeting the same guy again, he will not tell you the same things again. If neither of you has any news, then no one says anything.

2.4- And no central server

Author of the image: I would love to give you the proper credits. Really.

Sometimes I keep thinking about the amount of things I’ve posted on Facebook and how much of my “life log” is deposited in the hands of this people that may very well, from day to night, simply shut down the servers or suffer an attack and lose data or things like that. The cloud is extremely comfortable and practical, but certain things make me shiver — especially this feeling that my data is not exactly mine. And that it is an effort, which I'll not always do or will remember to do, to back up my stuff.

With SSB, everything you do is saved locally in your ~/.ssb directory. Keep a backup of that, and then a backup of the backup, and you'll be fine.

But again: since your data is now also distributed, losing them permanently can be a challenge — just like the data from a git repository with many clones: copies of your updates are on the machines of the people who follow you.

3- Getting your feet wet!

Before giving technical details, I see that we can get our hands on the dough to at least “feel” how things work in the SSBverse.

3.1- Desktop: Install and use the “Patchwork”

I’m learning to love these “AppImages “. For those who, like me, use Linux, just download the AppImage and run it:

Or, for the terminal people, like me:

# wget ''
# chmod a+x Patchwork-3.8.10-linux-x86_64.AppImage
# ./Patchwork-3.8.10-linux-x86_64.AppImage

You will see a microblogging-like application open on your desktop.

3.1.1- Now, take the time to save your identity

The details will come in the technical section, but your identity will come down to the contents of the .ssb/secret file. My recommendation: save a copy of it in a safe place. Losing this file is like losing (forever) the password of your ~ MySpace ~!

3.1.2- Connect to some “Pub”

When you run Patchwork — or SSB, for that matter — for the first time, you have no connection to anyone. You’re on an “island”, so to speak.

If there is another SSB user connected on the same LAN, you will see it in the list of connected people in the Patchwork sidebar as well as the people he follows. This is a good start. But if you want to “go to the tavern”, you can connect to a “Pub”, which is a place where several other users are connected too.

The official pub list ( is a bit outdated. I chose to connect to this one:

3.2- Mobile: Install and use the “MMMMM”

It’s a fairly “alpha” app, yet, but it’s almost usable.

4- Technical Details

4.1- “Scuttlebot” or “Secure Scuttlebutt” ???

The SSB has a big problem: the publicity materials are not very appealing, both visually and in content. Compare it with IPFS or Zeronet — which are not perfect, but much more “sexy” in a way. And the documentation, in addition to being rather sparse, is sometimes very confusing. So I need to explain what I myself took a little while to understand:

Scuttlebutt = the old, original protocol.

Secure Scuttlebutt = the improved and currently used protocol.

Scuttlebot = an implementation (and currently the main one) of a Secure Scuttlebutt server.

Patchwork = an application that makes use of the Secure Scuttlebutt protocol and connects to the Scruttlebot server.

4.2- The protocol

Best tutorial about the protocol:

Very complete, simple enough to be understood. Great for anyone planning to implement their own server.

4.3- The data model

Perhaps this is the part that ends up being more confusing: there is no data model. There are a few “standards”, yes, but these seem to have been created along with the applications that run over the protocol, such as Patchwork. That is: you can create different data types and create your own application using that same protocol, but in a different way.

I'm even planning to create my own application so people can share and organize their photos more easily .


4.4 Identities and feeds

Your identity is your public key.

Your signatures you create with your private key.

Each identity can have a feed.

You follow feeds. Or, in other words, you follow identities.

The feeds are, each one, a kind of blockchain . But at least it’s one blockchain per identity , not a huge global blockchain terabytes large that you need to download whole before you even know if that SSB is for you of not.

That simple.

~ Imagine that! Ahuge global blockchain terabytes large of which everyone would need to have a local copy! Haha! Who would use such a thing? ~


Secure Scuttlebutt is a distributed network protocol based on real-life social interactions, not concerned about being “real-time”, but able to work on “extreme topological situations” such as non-internet-connected devices. It is already quite functional, but has plenty of room for exploration and many interesting opportunities for “pioneering”.

Oh, and if you are using Patchwork, follow me:




Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Cléber Zavadniak

Cléber Zavadniak


Cristão reformado, arquiteto e desenvolvedor de software — Feel free to pay me a coffe — BTC: bc1qdcl4qdkendawzhxs6cuextlckw20jzwmjqm7lr