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:
- Getting an invitation from a friend
- Purchasing an Urbit ID from a third party, such as urbit.live, OpenSea, planet.market, or Urbit Marketplace.
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.
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:
urbit: the interpreter that runs when you run a command like
./urbitin your command line
arvo: the deterministic OS that lives in a directory whose name matches your Urbit ID, i.e.
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
We provide static binaries for macOS. You can grab the latest stable release as follows:
curl -O https://bootstrap.urbit.org/urbit-v0.10.7-darwin.tgz tar xzf urbit-v0.10.7-darwin.tgz cd urbit-v0.10.7-darwin ./urbit
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-v0.10.7-linux64.tgz tar xzf urbit-v0.10.7-linux64.tgz cd urbit-v0.10.7-linux64 ./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
urbit is the urbit executable downloaded with
Please note that this method of installing Urbit is more experimental, and we may not be able to assist you if you encounter issues related to WSL 2, but these instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the Windows Subsystem for Linux 2, an initiative by Microsoft to bring Linux to Windows 10. For Urbit to work, it is necessary to install WSL 2 and not just WSL, since version 2 uses virtualization and the real Linux kernel under the hood. Currently, WSL 2 is only available if you have signed up for the Windows Insider Program (the ‘Slow’ ring is sufficient), but this will change soon as WSL 2 is scheduled for general release in 2020.
Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Linux installation instructions above. For performance reasons, do not install Urbit in the mounted Windows volume, but install it in the Linux file system. For example, in your home directory, by typing
The latest version of WSL 2 also supports port forwarding, so you should be able to open Chrome on Windows and browse to port 80 on localhost (or port 8080).
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
If you are not already within the directory you installed above, enter it by running
cd urbit-v0.10.7-darwin (for Mac) or
cd urbit-v0.10.7-linux64 (for Linux) from where you ran the install commands. It contains your Urbit binary, and your ship will be installed here as well.
Once you're inside, 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 either the
~sampel-palnet:chat-cli/ prompt. If you're seeing
Ctrl-x to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
To shut down your ship, use
To start your ship up again, run
./urbit sampel-palnet/ from the directory
where your Urbit binary is saved. Note that in this usage,
sampel-palnet/ is the path of a folder, which by default is located in the same folder as
the Urbit binary. This folder is called your ship's pier, and you
can put it wherever you like.
Never boot multiple instances of your ship at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
Updating to the latest binary
Most updates to Urbit are downloaded and applied automatically as OTA (Over the
Air) updates. Occasionally it would be infeasible to distribute an update this
way, and a new
urbit binary is released. This is announced in the urbit-dev
Google Group when it occurs (as are all OTA updates). To update to the latest binary, follow
the same process outlined above to download and extract it into a new folder
(the binary linked on this page will always be the latest). Then run it as
Welcome to your ship! Let's try our first command in the Dojo, the Arvo command line and Hoon REPL, to get oriented.
(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. Now let's run our first useful command in the Dojo. The first thing you generally want to do with a new ship is to mount it. A ship being mounted means that it has a presence on your Unix filesystem, allowing files to be shared between Unix and your ship. To mount your ship, type
|mount % at the Dojo prompt.
|mount % >=
>= output means that a command was successful. Now you can see your ship's files in its Unix directory.
Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. To get onto Landscape:
- Start your ship. In the boot messages, look for a line that says something like
http: live (insecure, public) on 80. The number given is the port that your ship is using.
- If the port given is 80, simply type
localhostinto your browser's address bar. If the given port is a different number, such as
8080, you would type
localhost:8080. Alternatively, you access landscape by navigating to
ship.arvo.networkinto your URL bar, where
sampel-palnetis the name of your ship, without the
~. You will need to set up DNS proxying to use this option.
+codeinto your ship's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
- You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
Joining the community
Once you are in Landscape we recommend joining the Urbit Community group. You
will need to obtain an invite, which can be had by first joining
~/~dopzod/urbit-help chat channel and asking for an invitation from there.
This is most likely to succeed quickly during standard US West Coast working hours.
Once you have the invite you can accept it by navigating to your Groups by
clicking on All Groups in the upper left hand corner of Landscape, then Manage
All Groups, and in there you should see an invitation. From this interface you
can join the various Chat, Publish, and Link instances contained in the group.
You can join
~/~dopzod/urbit-help from either Landscape or chat-cli. To join from
Landscape first click on the Messaging tile on the home screen. Then press Join Chat
in the upper left corner and enter
~/~dopzod/urbit-help into the prompt and
press Join Chat. To join from chat-cli, first make sure your console has been switched from Dojo to the
:chat-cli application by pressing
Ctrl-x. The prompt will display
~sampel-palnet:chat-cli if in the correct mode. Then type
;join ~/~dopzod/urbit-help and press Enter.