Install + Setup

Urbit is not yet ready for everyday users — but if you're technically inclined or generally intrepid, feel free to try it out. It's a good place to explore.

In order to get going on the network, you'll need an Urbit ID. To try the live network out with a disposable identity, you can always create a comet.

Getting an Urbit ID

For an introduction to Urbit IDs and the address space more generally, see Urbit ID in Understanding Urbit.

While Tlon does not currently sell or distribute Urbit IDs, there are still a few ways to get your own Urbit ID:

Tlon occasionally selects candidates to distribute invitations, and users operating galaxies and stars can spawn and distribute a finite number of stars and planets, respectively.

Using your Urbit ID

If you have an Urbit ID, you'll use Bridge to get your ship's keyfile before you can boot your ship. For more information on how to use Bridge, see Using Bridge.

Install Urbit

The Urbit binary runs nicely on a Unix-like operating system – Ubuntu, Fedora, or macOS, for example. If you're using Windows, you'll need to get one of the aforementioned systems. But first, some terminology:

We have different installation instructions for different platforms. To install and run Arvo, the Urbit operating system, and its binary, run the commands that are listed for your operating system.

You can check your Arvo installation on any platform by running the ./urbit command. Installation was successful if you get a block of output that begins with the line below:

Urbit: a personal server operating function

macOS

We provide static binaries for macOS. You can grab the latest stable release as follows:

curl -O https://bootstrap.urbit.org/urbit-darwin-v0.9.2.tgz
tar xzf urbit-darwin-v0.9.2.tgz
./urbit

Linux (64-bit)

We also provide static binaries for 64-bit Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). You can get the latest stable release similarly:

curl -O https://bootstrap.urbit.org/urbit-linux64-v0.9.2.tgz
tar xzf urbit-linux64-v0.9.2.tgz
./urbit

To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:

sudo apt-get install libcap2-bin
sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit

Compile from source

If you want to compile from source, see the instructions on GitHub.

About swap space

If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, you can safely ignore this section.

Urbit wants to map 2GB of memory when it boots up. It won’t necessarily use all this memory, it just wants to see it. On a normal modern PC or Mac, or on a large cloud virtual machine, this is not an issue. On some small cloud virtual machines (Amazon or Digital Ocean) the default memory configuration is smaller than this, and you need to manually configure a swapfile.

Digital Ocean has a post on adding swap here. For Amazon there’s a StackOverflow thread here.

Booting your ship

Now the rubber meets the road. You'll be booting your ship with the keyfile that you downloaded from Bridge.

Note that this section is only for booting a ship that uses the live Arvo network. If you just want to create an unnetworked ship for development purposes, read this guide instead.

Step 1: Find Your Urbit ID

This will look something like ~lodleb-ritrul. You can see the name of your Urbit ID when you log into your wallet using the Bridge client.

Step 2: Find the path to your keyfile

Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.

Step 3: Run the boot command

Type cd in your terminal to return to your home directory. If you want to store your ship somewhere besides your home directory, change the terminal's working directory to the desired directory.

Run the command below, except with sampel-palnet replaced by the name of your Urbit identity, and path/to/my-planet.key replaced with the path to your keyfile:

./urbit -w sampel-palnet -k path/to/my-planet.key

Or, if you'd prefer to copy your key in, you can run:

./urbit -w sampel-palnet -G rAnDoMkEy

Either command will create a directory called sampel-palnet/ and begin building your ship. It may take a few minutes.

When your ship is finished booting, you will see the ~sampel-palnet:dojo> prompt. At that point, you should permanently erase your keyfile from your machine.

The Dojo

Welcome to your ship! Let's try our first command in the Dojo, the Arvo command line and Hoon REPL, to get oriented.

Type (add 2 2) into the Dojo. You should see the following:

~sampel-palnet:dojo> (add 2 2)

When you press Enter, you should see this:

> (add 2 2)
4

Good, your Dojo is working correctly.