[ /howto/patchwork ]

I first heard of Patchwork at the end of April 2016. I kicked the habit of using social networks some time ago, but the particular model that Patchwork employed seemed pretty interesting.

Being fairly comfortable with a lot of the technology behind the software, I felt I was in a good position to give it a try. I figured even if I wasn't really interested, if I liked the software I could at least relay my experiences to friends who might be interested.

After using it for about a day I decided I enjoyed the communication medium, and I started playing around with the source a little bit. I was in a good position to speak to some of the developers, and I got a little bit of insight into how to approach things.

I found a minor bug (and someone else affected by the same issue), fixed it, submitted a pull request, and got it merged without much difficulty. I've found that the ease of getting a fix merged into a codebase to be an effective metric of how the community will grow, so after this I decided that I'd be happy to get more involved with the project.

I haven't yet written any negative reviews of any software. When something good catches my eye, I try to give it a positive review, and write a little guide about how other people can use it. This is that review (for Patchwork).

What is Patchwork?

p2p social sharing

Patchwork is a decentralized social network.

my profile

Users run a server on their own machine. It finds some way to connect to the social network (this means connecting to another user who is already connected). Becoming friends with another user means hosting their content (and having them host yours).

When you go offline, your data persists via those who have already downloaded it.

Since you run patchwork locally, the app is able to detect when friends are nearby (on the same local network). This makes it really easy to help a friend join the network, since you can just click their icon to subscribe.

my local network

How does it work?

Patchwork is built on top of Secure Scuttlebutt, which is described as

a secure database with replication that is guaranteed to work

Each user has a private-public keypair which they can use to cryptographically sign a message, proving that they published it.

my activity feed

A first user (Alice) can publish a feed of these messages, where each message links to the previous message. Messages can be appended in this fashion, but not removed.

A second user (Bob) can subscribe to Alice's feed. Bob will attempt to download all messages in Alice's feed. The first time he connects, this fetches all of Alice's messages. The next time he connects, he determines if there are any new messages, and only downloads those.

Alice can in turn follow Bob, and the process is the same. Patchwork uses this mechanism to build a social network.

Your messages are distributed through a network of friend to friend connections without requiring you to trust the whole network, since your messages cannot be forged without an adversary having gained access to your private key.

Getting around the NAT problem...

One of the main reasons we have the more widely known social networks is that most users of the internet are not able to connect directly to each other. They don't have their own publically routable IP address, and so a third party which acts as an intermediary becomes necessary.

You post your content to facebook/twitter/g+/dropbox/??? and then your friend views it there.

Typically a user's computer has an address, but it's delegated by another device (a router) which might have a publically routable address itself. To reach your device, a process called Network Address Translation has to take place.

Rather than try to approach this problem, Patchwork has users connect to Public Peers which have static, publically routable addresses. These peers act as a meeting place where mobile or otherwise inaccessible peers can leave messages to be retreived by their friends at a later time.

Since I'm already running cjdns (which solves the NAT traversal problem by routing among cryptographically generated IP addresses), I could use my laptop's cjdns IPv6 as a publically routable address. Doing this with a desktop or microcomputer (like a Raspberry Pi or Lime2) would provide better guarantees of uptime.

Other cjdns users have already launched pubs on their nodes. Interestingly, Patchwork recognizes these nodes as being on my local network.

my 'local' network

If you want to join the network, and you're able to connect to my node on via cjdns, you can contact me and ask for an invite code.

What about my privacy?

Patchwork has a few really nice properties in terms of efficiency and authenticity, but there are some tradeoffs.

In addition to its feed publishing features, Patchwork can also send direct messages between users.

Messages are encrypted such that the intended recipient will be able to decrypt their contents. The message is then appended to your feed for the recipient to fetch the next time they update their feed.

If you intend to have a long conversation in private, determined adversaries could analyze the timing of your messages and the structure of the social graph to guess who is participating in the conversation.

As such, the contents of your data are safe, but your interactions may not be perfectly anonymous.

You should understand that this is a social network, and that its aim is to function without requiring centralization. If you're really worried about people tracking certain interactions, I'd recommend you use a different service.

Patchwork is a very suitable platform for effectively distributing messages which are meant to be public and persistent.

Your node in the Patchwork network will connect to various other peers in the network. If you're worried about your IP being exposed, I would recommend using a VPN (cjdns works well enough for me).

There's more information about how Patchwork's privacy model available here

What is its average resource consumption?

I've followed 30 people so far, and have been running Patchwork for a little less than a week. My local database has grown to use 57MB of disk space.

my friends

It's difficult to say how much space you should expect it to use, because it will depend not on how long you have used it for, but rather:

  1. how long those you follow have used it...
    • you will sync their entire feed, not just messages from the time you first follow them.
  2. how active those you follow have been...
    • if you follow someone who publishes a message every minute it will require more storage than someone who publishes once a day.
  3. what kind of content is shared by those you follow...
    • Patchwork users can share more than textual messages: images, git repositories, and lots of other content can be distributed over the same network

So far, disk usage hasn't concerned me. Disk space is cheap these days, and I could easily store a lot more messages on one of my mobile devices.

I still have to check how much network bandwidth it uses. I doubt it's optimal, since there is some background activity as the app syncs messages between other clients (you can watch your terminal as the app runs if you're curious about what it's doing).

Nevertheless, if you understand a bit about the web and how other social networks (facebook/twitter) work, you know that every time you visit their feeds you download the same messages over and over. Patchwork downloads messages once.

After storing them on your hard drive, you can read your feed over and over without ever downloading them a second time. This also means you can use Patchwork offline, though I'm not sure whether there is a mode for accessing the database without performing the background synchronization tasks.


There is no client for Patchwork in the cloud, it is only run locally. You can consider that a bug or a feature, as you like.

Installation requires Nodejs and some other tools, and so far you need to know your way around the command line (just a little bit).

A full explanation of how to install is available here.

For casual usage

You can install from npm.

# install it
sudo npm install ssb-patchwork -g;

# run it

Once it's running you can visit your local server in your browser via http://localhost:7777.

There are a number of releases, a Debian package, and support for even more package managers Coming Soon™.

For development

I find Patchwork particularly interesting because it's run locally, which means that you can customize your local installation however you want as long as you don't break the basic functionality which allows your node to communicate with other nodes.

If you want to hack on Patchwork you should install from Git.

From there, you can read through the docs/ directory for a better understanding of the codebase.