git.iko.soy/urbit.org
on fc4d4cb help sign in
urbit.org/content/using/install.md
246 lines 13 kB history raw
1+++
2title = "Install + Setup"
3weight = 1
4description = "How to install Urbit."
5template = "page_indiced.html"
6aliases = ["/docs/getting-started/"]
7+++
9This guide covers how to install and set up your own planet (or comet), but installation for a star is exactly the same. You will first install the Urbit binary, then you will either boot a comet or a planet. It's not too difficult, but if you would prefer to have someone run your urbit for you, consider a [hosting provider](#hosting-providers).
12## Installing Urbit
14You'll want to install Urbit binary first. Follow the instructions below to install the binary on Windows, MacOS, or Linux.
16### Windows
18> Please note that this method of installing Urbit is experimental, and we may not be able to assist you if you encounter issues related to WSL 2.
20Urbit cannot run on Windows itself, but there is a convenient way to run Linux using the [Windows Subsystem for Linux 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) on Windows 10. Install the Windows Subsystem for Linux 2 and open a Linux terminal in Windows, then follow the Linux installation instructions below. These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS, as demonstrated in `~sitful-hatred`'s step-by-step setup guide [here](https://subject.network/posts/urbit-wsl2/).
22For 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, which can be navigated to by entering `cd ~`.
24### macOS {#macos-and-linux}
26**The macOS binary does not work on M1 macs. Sorry. We're working on an M1 release**
28```sh
29mkdir urbit
30cd urbit
31curl -JLO https://urbit.org/install/mac/latest
32tar zxvf ./darwin.tgz --strip=1
33./urbit
35```
36### Linux
37```sh
38mkdir urbit
39cd urbit
40wget --content-disposition https://urbit.org/install/linux64/latest
41tar zxvf ./linux64.tgz --strip=1
42./urbit
43```
45Once you've followed the appropriate install instructions, you can check if everything went right by running the `./urbit` command. Installation was successful if you get a block of output that begins with the line below:
47```
48Urbit: a personal server operating function
49```
51To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
52```sh
53sudo apt-get install libcap2-bin
54sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
55```
56(Where `urbit` is the urbit executable downloaded with `wget` prior)
58### Choose to boot a comet or a planet
60If you just want to try Urbit out, you can use a comet. These are disposable, free identities, that are good for people who are new to Urbit and want to check out the network, but they aren't good for building a reputation as a friendly and responsible resident. Their long names (example: `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`) make them difficult to remember—and some communities ban comets to prevent spam—but they're still a good way to see what Urbit is about before buying your own planet.
62To start with a comet, continue below. For planet instructions, see [further below](#boot-your-planet).
64## Booting a comet {#comet}
66To boot a comet, go into the command line and run the following command from the `urbit` directory you created during [Urbit installation](#installing-urbit):
68```sh
69./urbit -c mycomet
70```
72Since your identity on the network is not verified, it may take up to an hour to generate your comet. As it boots, it will spit out a bunch of boot messages and create a directory called `mycomet`. Toward the end of the boot process, you'll see something like:
74```
75ames: on localhost, UDP 31337.
76http: live (insecure, public) on 8080
77http: live ("secure", public) on 8443
78http: live (insecure, loopback) on 12321
79~sampel_marzod:dojo>
80```
82When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).
84Get your password to log into landscape (the Urbit web interface) by typing:
86```sh
87+code
88```
90To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
92To start your comet up again, run the following from your `urbit` directory (note the lack of `-c` argument):
94```sh
95./urbit mycomet
96```
98### Updating your comet {#updating}
100The Urbit binary comes with a somewhat recent release of the Urbit OS, but ships can update automatically ("over the air"), so new binaries aren't necessary every time it's updated. Planets have automatic updates enabled by default, but this is not the case for comets. Many comets are used only once and thrown away, so it would be wasteful to update every single comet as soon as it boots. If you plan to use your comet for more than a quick test, you'll probably want to ensure you're running the latest version of the OS.
102You can enable updates for your comet by typing `|ota (sein:title our now our) %kids` into Dojo and pressing Enter.
104```
105> |ota (sein:title our now our) %kids
106>=
107```
109If you want to make sure you'll get updates, you can check by typing `|ota` with no arguments:
111```
112~sampel_marzod:dojo> |ota
113OTAs enabled from %kids on ~marzod
114use |ota %disable or |ota ~sponsor %kids to reset it
115> |ota
116>=
117```
119Now that you’re up and running, skip ahead to the [Setup guide](#setup).
121## Booting a planet {#boot-your-planet}
123There are two options for getting started with a planet. You can purchase one on your own and run Urbit yourself, or you can purchase a planet and hosting services through a [hosting provider](#hosting-providers).
125### Purchase a planet
127There are a few ways to get your own planet:
129- Getting an invitation from a friend.
130- Purchasing a planet, including hosting, from a [hosting provider](#hosting-providers) such as [geturbitid.com](https://www.geturbitid.com/).
131- Manually setting up and hosting an planet purchased from a third party such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), [urbit.me](https://urbit.me), [urth systems](https://urth.systems/), or [Urbit Marketplace](https://urbitmarketplace.com/).
133Note that when you buy a planet, you should ensure with the provider that your parent star is operating. If you need to escape a non-operational star, see [Escaping A Sponsor](@/using/operations/using-your-ship.md#escape).
135### Hosting Providers {#hosting-providers}
137Hosting providers will often sell you a planet and run it for you. This option is very simple but will probably cost a regular fee.
139Urbit is designed to be portable. This means that if you sign up for hosting now but later want to leave your hosting provider and run your Urbit yourself, you should be able to work with them to obtain all of your data and boot your planet back up without losing anything.
141Using hosting does mean that you're trusting your provider with your data, but so long as you have your planet, you'll always own your identity.
143Current hosting providers are:
145- [Tlon Corporation](https://tlon.io): Tlon is the creator of Landscape and is primarily responsible for the creation and maintenance of the Urbit project itself.
146- [Get an Urbit ID](https://www.geturbitid.com/): Get an Urbit ID was the first hosting provider and is run by a member of the Urbit community.
149### Choose to run your planet on your computer or on a cloud service
151Urbit must run on an existing computer somewhere. Most users run their planet on their personal computer, but we recommend eventually using a cloud service (Digital Ocean, Linode, etc) because it allows your planet to be accessed from anywhere on multiple devices. Hosting your planet in the cloud also allows it to always be online and ready for automatic updates. You are welcome to run from your personal computer and switch to the cloud later...all without losing any data!
153There is a guide for [hosting your planet on DigitalOcean](@/using/operations/hosting.md) and [hosting your planet on Linode](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps), but any cloud hosting service should work.
155### Get your keyfile {#keyfile}
157If you received an email invite to Urbit, the master ticket should be a .pdf file in the passport folder inside the archive that you downloaded. **If you bought your planet or someone sent you one you probably do not have a master ticket, and you probably don't need one. Do not issue a new master ticket unless you are sure you need to.**
1591. Connect to [Bridge](https://bridge.urbit.org). (Bridge is like an Urbit wallet)
1602. Enter the name of your planet and the associated master ticket if you have one. Click the "Metamask, Mnemonic, Hardware Wallet..." button if you don't have a master ticket.
1613. Once you're logged in, click the "OS" option.
1624. Click the "Download Arvo Keyfile" button. If this is grayed out, click on "Reset Networking Keys", then click on "Reset Networking Keys" on the following page, validate the transaction using your wallet, and then click "Send Trasaction". Once the transaction is complete, the "Download Arvo Keyfile" button should be available for you to press. You should receive a `.key` file that contains the secret needed to boot your planet. Hold onto this file.
164### Run the boot command {#the-dojo}
166Navigate to your `urbit` directory.
168Open your keyfile (it is just a text file) and copy the key inside. Paste it into the following command, with `sampel-palnet` replaced by the name of your planet. **Do not include the tilde in your planet name.**
170```sh
171./urbit -w sampel-palnet -G rAnDoMkEy
172```
174Or you can copy the keyfile into the current directory and run:
176```sh
177./urbit -w sampel-palnet -k ./my-planet.key
178```
180Either command will create a directory called `sampel-palnet/` and begin booting your planet. It may take a few minutes.
182When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo: the Urbit command line).
184Get your password to log into landscape (the Urbit web interface) by typing:
186```sh
187+code
188```
190To shut down your planet, use `Ctrl-D`.
192To start your planet up again, run the following from your `urbit` directory.
194```sh
195./urbit sampel-palnet
196```
198Note that `sampel-palnet/` is the path of a folder, which we just created in your `urbit` directory. This folder is called your planet's **pier**, and it holds all of your data.
200Never boot multiple instances of your planet at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
202**Important:** once a key has been used to boot a planet onto the network, it cannot be used to boot that planet again later - doing so will cause communication problems with other planets. For this reason you should **delete the keyfile from your machine once your planet has booted successfully**. If you do use the same key twice, you'll need to reset your planet to restore its functionality.
204Delete the keyfile with the command below:
206```sh
207rm ./my-planet.key
208```
210## Setup {#setup}
212The first thing you generally want to do with a new planet is to **mount** it. A planet being mounted means that it can be seen by Linux, allowing files to be shared between it and your planet. To mount your planet, type `|mount %` at the Dojo prompt.
214```
215|mount %
216>=
217```
219The `>=` output means that a command was successful. Now you can see your planet's files in its directory.
221To understand what happened with this command, read more about Urbit’s filesystem (called “clay”) [here](@/docs/tutorials/arvo/clay.md).
223### Using Landscape
225Landscape is the Urbit web interface, and it's the best way to interact with your planet. To access Landscape:
2271. Start your planet. 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 planet is using.
2282. If the port given is 80, and you are running Urbit on your personal computer, simply type `localhost` into your browser's address bar. If you are running urbit on a cloud server, type the ip of your cloud server. If the given port is a different number, such as `8080`, you would type `localhost:8080` or `your-cloud-ip:8080`. You'll be met with a login prompt.
2293. Type your password you got from running `+code` above.
2304. You're in! Now you can explore groups, join chat channels, share links, and much more.
232### Join a group
234Now that you're on Landscape, join the Urbit Community, a great place for newcomers to ask questions.
236Click the `Join a Group` button, then enter `~bitbet-bolbel/urbit-community` into the field and press the `Join Group` button.
238From the Urbit Community group you can join a variety of chatrooms, notebooks, and collections.
240### Next Steps
242Now that you’re up and running, take some time to deepen your understanding by checking out some of our other guides:
244- [Host your Ship in the Cloud](@/using/operations/hosting.md): Follow this guide to set your ship up to run as a cloud server, accessible from anywhere.
245- [Read the Operations Manual](@/using/operations/using-your-ship.md): Become an expert pilot by learning to use your ship.
246- [Learn to Develop on Urbit](@/using/develop.md): Learn how to contribute to or develop on Urbit.