[ /howto/ssb/scuttlebot ]

My previous article talked a little bit about what the SSB protocol is for, and why it's useful. This article will cover how to actually use a functioning implementation.

You can do more with scuttlebot if you have a public address that others can reach. If you don't have a static, publically routable IPv4 address, you can still use cjdns to connect to Hyperboria via our public peer listings.

With a minimal setup, this should at least allow other scuttlebot users to bypass restrictive networks and connect to your scuttlebot server.


Scuttlebot provides:

  1. A daemon which synchronizes data with peers in the background
  2. A client which connects to your local server and interacts with your own, and your peers' data feeds

Your server can synchronize with peers without having a public address, but someone needs to have a public address in order to facillitate introductions.

Various scripts and full featured apps have been built using the client. Typically, they all connect to the same server, and share an identity.

Messages published through your server typically contain enough metadata for applications to determine whether or not they should care about that message.

It is always necessary to have a running server before you attempt to use the client. The first time you run your server, it will generate the keys which are necessary for its cryptographic functionality. You'll be able to find your server's datastore in ~/.ssb/.


I'm assuming you have a relatively recent version of nodejs installed. If you don't, I suggest installing it using NVM.

You can install from git, but it's sufficient to install via npm, with:

npm i -g scuttlebot


If you have a publicly routable ip address, launching your server is as simple as:

sbot server
# this command doesn't terminate
# so run it in its own terminal

Assuming you have a hostname which points to your cjdns ip address, you can launch your server with a flag so that it uses that hostname:

sbot server --host=example.com

Note: Unfortunately, at the time that I am writing this there is a small issue with just using a raw cjdns IPv6 address. This should be fixed soon.

With that running in its own terminal, you can now use the client to interact with the server.

Finding your id

You'll need to know your sbot id in order to run some other commands. Your id is a random string, not something readable or especially memorable.

sbot whoami

This should print something like:

"id": "@dABVXEERk+yJSzdrDRUfF8R6FlXG7h9PaXKXlt8ma78=.ed25519"

Naming yourself

Various apps built on scuttlebot allow you to give yourself a more memorable name.

Note: I use the id listed above. You should substitute your own.

You should also use your desired name instead of "john.doe".

As per the docs:

sbot publish --type about --about "@dABVXEERk+yJSzdrDRUfF8R6FlXG7h9PaXKXlt8ma78=.ed25519" --name john.doe

Publishing your first message

Now you can publish a message with some content attached. Once other users have followed you, they'll be able to see the message published from your username.

sbot publish --type post --text "hello, world"

Creating invitations for your friends

Now you probably want to actually interact with some other users.

You can do this by giving them an invitation to follow you. Your server will allow theirs to connect, and will synchronize your message history.

sbot invite.create 1

This should print a long string which you can share with your friend.

Assuming your friend has done the same steps listed above, they should simply be able to:

sbot invite.accept <code>

This will cause your node to follow theirs.

Redeeming your friends invitations

Now that your friends are following you, you probably want to follow them back.

You'll need to know their id (ask them to run sbot whoami).

Following them is as simple as publishing a message saying that you are interested in their messages.

sbot publish --type contact --contact @5HvLpAsyCNySZn+JC3K+xl69+xhY9DU7CMixz2asRFg=.ed25519 --following

Using applications

You can write scripts that work with your scuttlebot server, in bash (as above), or via nodejs (using the ssb-client module.

Of course, other people have already made a number of applications, and you can simply use those.

  • Patchwork
    • which I already covered in an earlier post.
    • note that patchwork bundles its own sbot server, so you'll have to run either sbot server OR patchwork
  • From cel
    • git-ssb
      • git repositories, issues, PRs, forks, and more, exposed through a web interface (or from the command line)
  • From dominictarr
    • Patchbay
      • a modular alternative to Patchwork
  • From evbogue
  • From Gwen Bell
  • From Matt
    • Ferment
      • A web portal offering similar functionality to Soundcloud
      • built using ssb for social interaction
      • using webtorrent for distribution of audio files
    • Patchwork-Next
      • a patchwork rewrite on top of the modular patchbay platform
  • ssb-dns
    • my first significant ssb app
    • a dns server which sources records from your ssb-store

These applications typically feature a graphical interface that makes the tasks listed above much simpler. Generally you can see a list of other users, and follow them with a single click.

Learning how to do it via the command line simply gives an idea of what is possible, and makes it more obvious that all of these applications wrap up this underlying functionality.

The great benefit of this architecture is that even though you may use an app to interact with the data, you can always access the same data with a custom script.

Whatever happens to the developers of each application, the information you put in is always accessible, never locked away on some remote computer that might disappear.