Getting Started

Getting started

Important details / long scenic drive version

large Hermies dancing

Ok, you’ve been hearing about Scuttlebutt and decided that “Yes, I do want to join an amazing social network with lots of good people that no company can control and also happens to also work offline.

Here’s an overview with the basics you need to know.

NOTE: If you have no time, and just need to get up and running ASAP, there’s the Quick Start.

First off Scuttlebutt is a protocol on which many different kinds of apps can be built.

As for the social network, there are many clients, just like there are many Twitter clients. It doesn’t really matter which one you use. They’re all talking on the same network.

Patchwork is the most polished client and it doesn’t require you to know any geeky stuff. The only caveat is that it just wants to run on one computer, and your identity is tied to the files on the computer you install it on. There are ways around this but it’s beyond the scope of this document.

Patchwork logo

Step 0: What is Scuttlebutt?

If you haven’t done so already go watch the Scuttlebutt Love Story video. Then come back.

Step 1: Install Patchwork

Download Patchwork, a Scuttlebutt app, and install it like any other app.

Step 2: Set up your profile

Start up Patchwork and set up your profile.

patchwork at first bootup

Choose a name. Names in Scuttlebutt are not unique, just like in the real world – you can be “Fern” even if there are other people named “Fern” already.

You don’t need to upload an image, but we recommend that you do, because it’s much easier to figure out who is talking when there’s a visual, and the defaults are really generic. Some people use a photo of themselves. Some people use a random avatar they like, just like on Twitter.

You can change this all later (name, photo, and description). It’s possible to discover your old names and photo and description, so consider the privacy implications of whatever you choose. You may want to start with a temporary-feeling identity and change it later once you settle in.

The description area like every text area in Patchwork uses markdown formatting.

Save that when you’re done.

Step 3: Connections to people and pubs

Create social connections and network connections.

Scuttlebutt is unusual so it’s worth understanding how this works:

Social connections (following someone) indicate that you’re interested in reading their posts. This is about the same concept as on Twitter. Your computer uses your social connections to know what data it’s interested in when it’s syncing.

Network connections happen when two computers find each other and try to exchange data. Your scuttlebutt app will try to connect with any other Scuttlebutt computers it can find just in case they have data about people you’re interested in.

So each person’s computer acts like a courier or mail carrier, ferrying around messages and giving them to other nearby computers that are interested. We call this process “gossip”.

Scuttlebutt downloads everything it can up front, so that it will work when you’re offline. In that way it’s like an email client such as Outlook or Thunderbird.

More about social connections and how posts travel

Your scuttlebutt app is interested in the people you follow, and the people they follow (2 hops out). It won’t show those more distant people to you in most screens of the app, but it will try to download their posts in case you try to look at them.

If you’re not following anyone, your computer won’t request any posts and there will be nothing for you to read. And if nobody is following you, your posts won’t get very far out into the network.

So your next task is to follow and become followed.

Connecting to people locally

If you’re sitting in the same room as someone, on the same wifi or wired network, your computers will discover each other. You’ll see them listed in the left sidebar under “Local”.

Click their profile to see more about them, and click “Follow” if you feel like following what that person has to say and helping to ferry their data around.

Your computers will talk to each other even if you’re not following each other, because you might happen to have gossip about a mutual friend to sync.

Pubs help you connect over a distance

“Pubs” are robot friends to get you started. Think of them as bartenders in a neighborhood pub who know a lot of people, and help spread gossip.

They work the same as actual people on the network, except you can get them to follow you by “joining” them with an “invite code”.

They exist for 2 reasons:

  • To create more social connections, like that friend of yours who knows everybody in town, so gossip can travel further and you can meet new people
  • To create easier network connections, since they’re always online and reachable from anywhere on the internet.

You don’t have to use pubs if you and your friends carry your laptops around and sync up in person from time to time. But if you want to find new people, or distant people, you should join a couple of pubs.

Time to join some pubs

“Joining” a pub causes you and the pub to become mutual followers.

Choose a pub from the list of pub servers.

From one of the pubs, click a button to “Get An Invitation” and it’ll generate a custom invitation code just for you. It will look like a long string of random letters and numbers, that make up the “invite code”. Copy the whole thing. Then click the “+ Join Pub” button in Patchwork at the top left, and paste the code into the input field.

Join Pub button

In case one of the pubs or invite codes might be broken, you may want to join a few pubs for better reliability.

If you’ve already got a friend on Scuttlebutt, try to join at least one of the same pubs as them so that you can see each other. (Ask them which pubs they’re on.)

Step 4: Getting all the Gossip

The first time you join the network there will be a lot to download and process. For real, expect this “syncing” process to take up to an hour and use a couple of gigabytes. This is completely normal, and yes probably not what some of us are used to.

It’s a good time to go have a cup of tea or rewatch the Scuttlebutt Love Story. Just know that we are using the web in a entirely different way.

Initial Sync Island

Patchwork is downloading the entire history of the all people you’re interested in. Once this is done you can use it offline!

It goes faster if you have a friend’s computer on your wifi because you can get most of the content from their computer instead of from across the internet.

There’s a progress bar at the top of the window. During this time it’s best to leave the app alone and not try to use it because it can seem slow or broken. It’s safe to quit and restart the app while this is happening, but just try leave the app open to do it’s thing.

Patchwork has a bug - after the first long syncing process is done you need to restart the app in order to see most of the content.

What are all these pubs listed in the Patchwork sidebar? I didn’t join those!

In the left sidebar is a list of “connected pubs”. These are network connections, not social connections.

You computer is talking to every computer it can find in case there’s relevant gossip to share. You haven’t necessarily “joined” those pubs, your computer is just looking everywhere for news from your friends.

The pubs you’ve “joined” show up on your profile page, mixed in with the people you’re following.

Step 5: Get Social!

woo yay! Congratulations! You’ve made it! 😊

The “Public” page shows you posts that your friends wrote or commented on.

The “Private” page lets you write private messages to up to 7 people at a time.

“Channels” are really more like hashtags on Twitter. The Active Channels list shows recently used channels, and you can find more in the More menu. Channels are useful for organizing topics of conversation, and for finding people to follow.

browse all button

There’s a search box in the top right. Start with ”@" to search for friends, "#" to find channels, or just put words you want to find.

We have a tradition that new people write introductions in the #new-people channel. The easiest way to get there is to search for "#new-people"

Sharing Scuttlebutt things with other people

We had a system to put Scuttlebutt content on the normal internet but it’s being phased out now. If you want to try it, right-click a post and “Copy External Link”.

The public viewer is kept running by the generosity of a community member not some mega-corp. with racks of backup servers. ;)

Only people who have opted-in to the public viewer will show up there. Check out the Privacy page for details.

Stay Happy and Safe

If someone is bothering you or saying things you don’t want to hear, you can block or ignore them from their profile page (in the Options button). This will hide their messages and comments from you.

You can loudly block someone, or quietly ignore them.

A block is public and everyone can see it. Blocking is a way to demonstrate community norms and alert your friends to someone they may also want to block. Sometimes it starts useful conversations.

Ignoring quietly is a secret action that only you will know about. It hides the person from your view.

We want Scuttlebutt to be a safe cozy place but there are still some things we need to fix:

  • Blocked people can see your public messages.
  • Content from blocked people is still on your computer. (This is almost fixed!)
  • Patchwork has some bugs that let you see blocked people in certain situations when they should be hidden
  • Scuttlebutt doesn’t provide IP address anonymity by itself, but you can use it with a VPN or Tor.
  • Messages can’t be deleted yet.

We know this isn’t enough safety for many people and we’re working on these issues now.