Urbit / Docs

Getting Started

This guide is broken into five parts:

  1. Acquiring an Urbit Identity

  2. Using Bridge

  3. Installing Arvo

  4. Booting Your Ship

  5. Basic Operations

If you just want to install the Urbit OS, Arvo, and don't need to be on the Urbit network, you can skip to Installing Arvo.

Acquiring an Urbit Identity

Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum blockchain. An Azimuth address, called a point, functions as an identity and a network address for Arvo, the Urbit OS. An instance of Arvo is called a ship. A ship can't use the Arvo network until it's combined with a point.

Throughout this guide, we'll refer to "Urbit identities" and "points" interchangeably.

Points are generally not freely available, so you will need to either purchase one or get one from a friend. This guide assumes you have found a way to acquire a point.

If you went through the address registration process and used Wallet Generator, then you should have have received a .zip file that contains an Ethereum address and cryptographic secrets in the form of a PDF.

Your ownership PDF contains two secrets that must be kept safe.

  • Master Ticket: This is a master key that allows you to manage every aspect of your address.

  • Ownership Seed BIP39 Mnemonic: The master ticket encoded as a BIP39 mnemonic for compatibility with most Ethereum wallet software, including our own Bridge client.

Using Bridge

Bridge is a client that we built for accessing and managing your Urbit identities. Like Wallet Generator, Bridge is a web application that can also be run in offline mode. It can be run in Firefox on all platforms, and also in Chrome if you're using a Mac.

Importantly, Bridge also allows you to generate a keyfile that

you will need to boot your ship on the Arvo network for the first time. Once you boot a ship with a keyfile, you can restart it later without the keyfile.

Note Bridge allows you to make writes to the blockchain, but we ask you to confirm anything that will incur a transaction cost. If you plan to do anything heavy-duty, make sure your Ethereum address has some pocket ETH.

Download Bridge here and follow the instructions below.

Step 1: Welcome

Click Unlock a Wallet.

Step 2: Select a Network

On the dropdown menu, make sure that Main Network is selected. Then click Continue ->.

Step 3: Unlock a Wallet

On this dropdown menu, choose how you'd like to access your Ethereum wallet. If you aren't using a hardware wallet (we support Ledger and Trezor), you'll want to use your Ethereum wallet's BIP39 Mnemonic.

If you used Wallet Generator to generate an HD wallet, you have a few choices: you can choose Urbit Master Ticket, which is high-value, but allows you unfettered permissions to update your point. The mnemonic associated with your management seed is also useful to perform everyday operations (such as boot your ship!).

Select the appropriate option and click Continue ->.

If you already have a point -- for example, if you are trying to boot a ship from a pre-Ethereum-era network -- you should see a list of points associated with your keys. If you are trying to boot a planet for the first time, click on the Details link for that point. At the bottom on the Details page, there is a section called Urbit Networking. If the fields in this section are filled out, proceed to step 6.

If you do not yet have a point and are getting one sent to you, proceed to step 4.

Step 4: Accept Your Transfer

If you were sent a point by a friend, then you should see a graphic under Incoming Transfers. Click the Details -> link under that graphic.

Now you'll be on the management page of your point. The transfer isn't completed yet, so click Accept incoming transfer. Then check both boxes and and click their associated Sign Transaction and Send Transaction buttons.

If you already own a point, then click on the Details -> under your sigil in the Your Points section.

Step 5: Set Your Networking Keys

If you just accepted a point, you'll be returned to your point screen. Notice that that links and buttons are now clickable. You now own this point!

Click the link that says Set Urbit networking keys. Bridge will let you either download a keyfile derived from your networking keys are you can paste in your own network seed and derive a new keyfile. See our HD Wallet Spec for more information.

It should be noted that this is an event on the Ethereum network and will cost a trivial, but non-zero, amount of gas to complete.

Step 6: Generate Your Keyfile

From the detail page associated with your point, click the Generate Arvo Keyfile button and you'll be taken to a page with a field titled Network seed. If you went through the address registration process, this should be filled in already. Click Generate ->, which will download a keyfile onto your machine.

With that keyfile in hand, you can now exit Bridge.

Installing Arvo

Now you're ready to run Arvo. You're almost there!

But first, some terminology:

  • vere or urbit: the interpreter that runs when you run a command like urbit or /bin/urbit in your command line

  • arvo: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie ~famreb-todmec lives in /famreb-todmec

Arvo runs nicely on a Unix-like operating system -- Ubuntu, Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need to get one of the aforementioned systems. Don't worry: most of them are free.

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

On any platform, you can check your Arvo installation 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

Dependencies

Urbit depends on:

C compiler (gcc or clang)
curses
git
gmp
libcurl
libsigsegv
libuv
meson
ninja
openssl
pkg-config
python2
zlib

Instructions

MacOS

We recommend using the Homebrew package manager to run Arvo on MacOS.

# Bash

brew update
brew install gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl
git clone https://github.com/urbit/urbit
cd urbit
./scripts/bootstrap
./scripts/build
sudo ninja -C ./build/ meson-install
urbit

Ubuntu or Debian

# Bash

sudo apt-get update
sudo apt-get install g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev make openssl pkg-config python python3 python3-pip zlib1g-dev ninja-build
sudo -H pip3 install --upgrade pip
sudo -H pip3 install meson

git clone https://github.com/urbit/urbit
cd urbit
./scripts/bootstrap
./scripts/build
sudo ninja -C ./build/ install
urbit

Fedora

# Bash

sudo yum upgrade
sudo yum install autoconf automake cmake ctags gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel libtool ncurses-devel ninja-build openssl openssl-devel pkgconfig python2 python3 ragel re2c wget

# meson requires python 3.5; RHEL supplies wrong version
pushd /usr/src
  sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
  sudo tar xzf Python-3.5.5.tgz
  cd Python-3.5.5
  sudo ./configure --enable--optimizations
  sudo make altinstall
  which python3.5
  cd /usr/local/bin
  sudo ln -s python3.5 python3
  hash python3
popd

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo /usr/local/bin/python3 get-pip.py
# downgrade meson to avoid dependencies that redhat can't meet
sudo -H /usr/local/bin/pip3 install meson


git clone git://github.com/ninja-build/ninja.git && cd ninja
git checkout release
./configure.py --boostrap
sudo cp ./ninja /usr/local/bin

git clone https://github.com/urbit/urbit
cd urbit
./scripts/bootstrap
./scripts/build
sudo /usr/local/bin/ninja -C ./build/ install
urbit

Arch Linux

# Bash

sudo pacman -Syu
sudo pacman -S curl gcc git gmp libsigsegv ncurses ninja openssl python
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python3 get-pip.py
git clone https://github.com/urbit/urbit
cd urbit
./scripts/bootstrap
./scripts/build
sudo ninja -C ./build/ meson-install
urbit
FreeBSD
# Bash or Sh

pkg upgrade
sudo pkg install curl gcc git gmake gmp libsigsegv python python3 ncurses openssl gmp
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
sudo python3 get-pip.py
sudo -H pip install --upgrade pip
sudo -H pip install meson
sudo pkg install ninja
git clone https://github.com/urbit/urbit
cd urbit
sh ./scripts/bootstrap
sh ./scripts/build
sudo ninja -C ./build/ meson-install
urbit
Amazon Web Services
# Bash

sudo yum update
sudo yum install gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel ncurses-devel openssl openssl-devel pkgconfig python2 python3 python3-pip wget git
sudo env "PATH=$PATH" pip3 install --upgrade pip
sudo env "PATH=$PATH" pip3 install meson


# we need libsigsegv
#

wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm

git clone git://github.com/ninja-build/ninja.git
pushd ninja
  git checkout release
  ./configure.py --bootstrap
  sudo cp ./ninja /usr/local/bin
popd


git clone https://github.com/urbit/urbit
cd urbit
./scripts/bootstrap
./scripts/build
sudo env "PATH=$PATH" ninja -C ./build/ install

urbit

Using a Fake Ship

Perhaps you want to boot a ship without an identity. We recommend doing that for development purposes, or if you just want to play around with an un-networked ship without getting a point. You can now use the command of the scheme below to boot a fake ~zod.

urbit -F zod

If you want to get on the Arvo network with your point, then continue to the next section.

Set Up Swap

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

Urbit wants to map 2GB of memory when it boots up. We won’t necessarily use all this memory, we just want 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.

Don’t spend a lot of time tweaking these settings; the simplest thing is fine.

Booting Your Ship

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

Step 1: Find Your Point's Name

This will look something like ~lodleb-ritrul. You can see the name of your point(s) 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 ~sample-planet replaced by the name of your Urbit identity, and path/to/my-planet.key replaced with the path to your keyfile:

urbit -w ~sample-planet -k path/to/my-planet.key

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

urbit -w ~sample-planet -G rAnDoMkEy

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

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

Basic Operations

Welcome to your urbit! There's a few things you should do to become oriented.

Dojo

Let's try out the Dojo, the Arvo command line and Hoon REPL:

~sample-planet:dojo> (add 2 2)

Should produce:

> (add 2 2)
4

Good.

Mounting

Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo prompt and run:

~sample-planet:dojo> |mount %

This should produce:

> |mount %
>=

which indicates that the command was processed.

|mount % will cause a home/ directory to appear inside your pier folder in Unix (the “pier” is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files are automatically synced into your ship.

Landscape

Landscape is web app we built for chatting and making posts. We are using Landscape to run a few experimental “cities” -- private discussion communities -- as a closed beta of sorts. If you have an Azimuth point, you’ll need to email us a request to gain access to one of these cities.

Once you're in a channel, you can also interact with it from the command line, if you so wish. Use ctrl-x in your ship's terminal window to toggle between the Dojo and the Talk prompts.

Shutting Down and Restarting

You can turn your ship off with ctrl-d from the Talk or Dojo prompts.

To restart your ship, simply pass the name of your pier:

$ urbit some-planet