Getting started
So, you're curious about Urbit… First off, welcome! It's great to see you here.
Urbit is a different kind of computer that will provide moments of "Wow" and some moments of frustration. It's also a work in progress, with some parts much more polished than others. So, let's work through this walk-through with a spirit of exploration.
The goal of this lesson is to launch your first Urbit ship, delete it, and in between get comfortable with the interface. We'll keep this risk-free possible so you can experiment with anything in these lessons without worrying about blowing anything up.
Downloading Port
We'll start by downloading an app that will provide a nice interface. From this link, chose a release that fits your computer. For example, because I use a Mac, I would choose Port.dmg. Follow the usual steps for installing software on your computer.
Once installed, the program's name is Port. Find and launch it.
Creating a comet
We start by creating a computer (in Urbitese: ship) on your computer. Urbit's design favours being connected, so moons, planets, stars or galaxies are all connected to each other. The second computer we'll create is called a comet and is is disconnected from other ships. Comets are free standing because they are designed to be throwaway; so they're great for exploring risk-free. Even once you own a planet, star, or galaxy, you might continue to spin up the occasional comet just to play around.
Start by selecting Comet from the Add Ship menu.
Then add details. The name can be (almost) anything meaningful to you, as you are the only person who will ever see it. It must use lowercase letters, no numbers or symbols other than '-' are allowable. The name helps find it later and throw it away when you're done exploring.
Urbit is like computer operating systems such as Apple's MacOS and Linux: designed to run in a terminal (think of those green screens from movies before the 2000s). Few people feel comfortable in the terminal, though, so Urbit provides a user interface in a browser. What this means is that there is a web server inside your Urbit ship. If you're technically savvy you and use multiple Urbit ships, you can set the port number, but it's unnecessary. Urbit is smart enough to detect other apps using a port it wants to use automatically and chose an empty one.
This will take a while; perhaps get yourself a bit of coffee.
Once your ship is ready, launch Landscape (Urbit's home screen). You will see the following screen.
There isn't very much to do here yet.
As a first step, exploring an app's preferences is usually a good way of learning what is possible. You can reveal the preferences by clicking on the top-left circle.
You can set a few things in settings, and there are settings for the install apps. This list of apps will grow as we explore more.
Heading Home
Once you've played to your heart's content, click on the button on the bottom-left of the window that says, Home. It will take you to a page that now shows all of your ships. Your latest ship will have a green dot and say "Running" as its status.
You can get back to Landscape (your ship's front page) by clicking Open.
Clicking on Manage will show options for stopping, troubleshooting and migrating your ship.
Managing an Urbit Ship
When you open the Manage panel, there are three main sections. The top section is pretty self-explanatory with controls to stop a ship and get back to Landscape. There is some useful information we'll explore in a further lesson.
As mentioned above, Urbit's design prioritizes the Terminal. We will explore it in a couple of lessons, but for now, let's skip it.
The bottom panel, Ship Migration, is where you can delete your ship. Because comets are expendable, let's delete the one we've been working on. Click Delete Permanently and then affirm that decision.
Comets can come and go easily, and we'll make use of that facility in the next few lessons.
Exercise
To end the lesson, go back to the home screen and create three comets that we will use in future lessons. Being a boring person, I named my three 'com-one', 'com-two', 'com-thr'; I'm confident you can do better than me!
Troubleshooting (What could possibly go wrong?)
At this stage, there is not much that can go wrong, but things taking a long time and needing an access key are two events that might provide sticking points.
Taking a Long Time?
The problem you're most likely to run into is that downloading takes longer than you think it should. Here's what's going on: Urbit is a peer-to-peer system, so the code you're downloading is coming from other people's computers. Those computers may be busy doing other things, have a poor network connection, or even be off-line (for example, if they're on someone's computer and the computer has fallen asleep).
Access Key?
When you are running multiple comets, you might see a screen that asks for an Access Key. Port makes it easy to find the key you need with a button at the bottom-left, beside the home button.
