There are two main ways to use Urbit: as a planet or as a comet. We said in the article about what is Urbit that there are a limited number of planets, which makes them valuable (usually around $10 in the market).
Comets, on the other hand, are free.
Besides the cost of acquiring a planet, since each user on Urbit works as a server, it is common for users to hire hosting services to run their planet 24 hours a day, which brings another extra cost of around $9 per month.
Fortunately, you don’t have to incur any of these costs if you just want to explore Urbit for the first time. It is possible to do everything for free via a comet, as we will teach you in this step-by-step guide.
1) Download the Urbit software
The first step is to download and install Urbit on your computer.
If you are a Windows user, we recommend that you first install the Windows Subsystem for Linux (WSL) and then come back here to follow the Linux commands, as we teach at the end of this article.
For MAC or Linux, you need to open the terminal/shell and type the following command:
For MAC computers:
curl -L https://urbit.org/install/macos-x86_64/latest | tar xzk -s ‘/.*/urbit/’ && ./urbit
For Linux computers:
curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk –transform=’s/.*/urbit/g’ && ./urbit
PS: make sure the comma used above is right (single comma ‘). We recommend you to edit this comma in your terminal to make sure the style is correct.
If everything went well, you should see the following message after installation:
Urbit: a personal server operating function
In this case, you can proceed to the step 2).
*If you encounter an error like “curl: command not found“, it means you first need to install curl before running the code above. Type in your terminal:
sudo apt-get install curl
Enter your password to grant permission, and if at any point the terminal asks a question like “Do you want to continue? [Y/n]“, type Y and press ENTER.
After installing curl, try entering the Urbit installation command again that had previously failed.
2) Create an Urbit identity: Comet
Since you have already installed Urbit, your computer’s terminal/shell/prompt is ready to recognize Urbit-specific commands. The first command you will use is the command to create an identity. Type in your terminal/shell/prompt:
./urbit -c myfirstcomet
You can replace “myfirstcomet” with any name you like. A folder will be created on your computer with this name, and all Urbit files created using this comet will be stored there.
It usually takes a few minutes to initialize the comet, but it can also take longer.
Once finished, your terminal will display a message indicating that you are now using the Urbit shell, called dojo. The message in your prompt will have something similar to this:
ames: live on 32457
http: web interface live on http://localhost:8080
http: loopback live on http://localhost:12321
~togtun_pocres:dojo>Don’t worry, this message is just providing information about the network and access. Ames is the name of Urbit’s network/communication protocol.
Notice that the field ~togtun_pocres:dojo> means that you can now send commands directly to the Urbit system, through its terminal called dojo. The name after the ~ symbol will be different from the one shown above, as it represents your Urbit identity.
Okay, now that you have created your comet, you can access the Urbit visual interface in step 3.
*If you encounter any errors when trying to run the ./urbit command on Linux, it’s probably because you don’t have the necessary permissions. This is easy to resolve:
If you’ve just installed Urbit, you’re already in the right directory, so you can simply use the command:
chmod +x urbit
And then try the command again:
./urbit -c myfirstcomet
If you’re not in the right directory, use the following command to search for it:
find ~ -type f -name “urbit”
Then navigate to the directory, which will be the full address before /urbit, for example, if the result of the command above was /home/myuser/urbit, use the following command to navigate to the correct directory:
cd /home/myuserAfter being in the correct directory and running the permission command, you can now type:
./urbit -c myfirstcomet
3) Open Urbit in your browser
Urbit’s visual interface can be accessed by any browser (like Google Chrome, for example). All you need to do is use the address bar (the same place where you type a website address such as google.com) and type http://localhost:8080
When you type this and hit enter, the Urbit visual interface will appear, like the one in the image below:
Understanding what happened: when you created an Urbit identity, the software automatically configured a port for your computer’s communication with the Urbit network. This port by default is port 8080 for Linux, so you typed localhost:8080. Eventually Urbit may have connected to another port, such as 80, or any other port, if it was already being used. To find out which port was used, look at the information that appeared in the terminal after you created a comet.
Ok, at this point, you only need a password to enter Urbit. Let’s get that password.
4) Log in with the given credentials
The last step before you can browse the Urbit network as a comet is to log in. The credentials can be obtained from the terminal/shell/prompt that you were using to install and create the comet, because the dojo is now available, so when you return to the terminal you were working in before, you will send this command directly to the dojo:
+code
Just type the command above and press enter in your terminal.
The login credentials (Access Key) will appear.
Copy this Access Key and use it in the Urbit visual interface that is already opened in your browser. Then click “Continue”.
Congratulations! You are now inside Urbit!
You will see a dashboard similar to this:
To learn how to use Urbit for the first time, exploring some applications and the ecosystem, read this article.
5) Shut down the comet
After navigating through Urbit, you can shut down your comet by typing |exit in the dojo or pressing Ctrl+D.
If you closed the Urbit terminal or turned off your computer, you can access Urbit again as a comet in two ways: by creating a new comet (in this case, just open the terminal/shell of your computer and follow steps 2) onwards) or by restarting your previously created comet.
For the latter case, use the code:
./urbit myfirstcomet
Replace “myfirstcomet” with the name you gave your comet and follow steps 3) onwards.
For Windows users:
Since Urbit is still under construction, it is common for some bugs to occur, especially for Windows users. This is why we recommend to use Linux, as it is more stable. The good news is that Windows 10 or latest offer native support for running Linux, through the Windows Subsystem for Linux (WSL).
This WSL allows you to run Linux applications and commands, as well as install complete Linux distributions on Windows.
To install the Windows Subsystem for Linux (WSL) on Windows, follow these steps:
1. Open the “Control Panel” and select “Programs and Features”.
2. Click on “Turn Windows features on or off”.
3. Scroll down to find the “Windows Subsystem for Linux” option.
4. Select the checkbox next to this option and click “OK”:
Important: Also check if the option “Virtual Machine Plataform” is selected!
5. Restart the computer when prompted.
6. After the computer restarts, open the “Microsoft Store” and search for “wsl”. Install.
7. Now you can search and install a Linux distribution of your choice (e.g., Ubuntu). Linux has different distributions, which are slightly different “versions” of the operating system. Any of them should work, but opting for popular distributions like Ubuntu is always a good choice.
8. Once the Ubuntu installation is complete, open the Start menu and search for Ubuntu. Click on the search result to launch the operating system.
9. The first time you start Ubuntu, you will need to set up a username and password.
If you’ve never used Linux before, you might find it strange that the cursor doesn’t move when you type the password. This is normal, the password is being processed, even if it doesn’t seem like it. So simply type your password and press ENTER.
That’s it! Now you have WSL installed and can run Linux commands and applications directly on Windows.
Now, whenever you want to use Urbit, first open the Ubuntu that is already installed and then follow the steps we showed in this tutorial as if you were in a Linux environment. In other words, perform steps 1) to 5) using the Linux commands, as you will be using the Ubuntu system to install and use Urbit.
Next steps
Now that you are inside Urbit, you can use the platform’s applications, as we explain in this article.
Check also: Urbit Course for Beginners
Return to: Urbit Guide