content/getting-started/cli.md · urbit.org

git.iko.soy/urbit.org

on bb3adff help sign in

urbit.org/content/getting-started/cli.md

205 lines 8.4 kB history raw

1+++

2title = "Command line install"

3weight = 2

4description = "Installation instructions for power users."

5+++

7If you're a power user, you can run the Urbit virtual machine directly using the command line. Choose the code for your operating system and run the commands in your terminal.

9<div id="os" class="os">

10 <input type="radio" id="macos" name="os" checked>

11 <label for="macos">MacOS</label>

12 <div class="tab">

14```bash

15mkdir ~/urbit

16cd ~/urbit

17curl -JLO https://urbit.org/install/mac/latest

18tar zxvf ./darwin.tgz --strip=1

19~/urbit/urbit

20```

22 </div>

24 <input type="radio" id="linux" name="os">

25 <label for="linux">Linux</label>

26 <div class="tab">

28```shell

29mkdir ~/urbit

30cd ~/urbit

31wget --content-disposition https://urbit.org/install/linux64/latest

32tar zxvf ./linux64.tgz --strip=1

33~/urbit/urbit

34```

36Linux users may need to run this command in another terminal window to access your Urbit on port 80:

38```shell

39sudo apt-get install libcap2-bin

40sudo setcap 'cap_net_bind_service=+ep' ~/urbit/urbit

41```

43</div>

45 <input type="radio" id="windows" name="os">

46 <label for="windows">Windows</label>

47 <div class="tab">

49> 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.

51Urbit 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/).

53For 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 ~`.

55</div>

56</div>

58If successful, you will see a block of output beginning with the line:

60```

61Urbit: a personal server operating function

62```

64### Booting a free identity {#comet}

66There are two parts to Urbit: an **ID** and an **Operating System**.

68You have just installed the Operating System on your computer.

70The **ID** is similar to a username and password on another site. The difference is that the public part (the username) is verified by thousands of people around the world while only you hold the key (the password) to that ID.

72There are five kinds of Urbit IDs but to get started you only need to know about two: we call them **planets** and **comets**.

74---

76**Planets** are scarce (this prevents spamming, among other things) and usually require a price to acquire. This is the recommended way to run Urbit, but it's a bit more involved.

78A planet name looks like `~sampel-palnet`.

80[Follow this guide](/getting-started/planet) if you have already acquired a planet.

82[Find a planet to purchase](/getting-started/planet#purchase)

84---

86**Comets** are practically unlimited and free to acquire. At present, these are a great way to try out the network for free.

88A comet name looks like `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`.

90[Read more about Urbit ID here](/understanding-urbit/urbit-id)

92---

94To boot a comet, go into the command line and run the following command from the `urbit` directory you created during [Urbit installation](#installing-urbit):

96```sh

97~/urbit/urbit -c mycomet

98```

100It may take a while to load the comet (probably only take a few minutes, but it could take longer). This comes along with it being free. When it's done you'll some messages ending like this:

101

102```

103ames: on localhost, UDP 31337.

104http: live (insecure, public) on 8080

105http: live ("secure", public) on 8443

106http: live (insecure, loopback) on 12321

107~sampel_marzod:dojo>

108```

109

110When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).

111

112To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.

113

114To start your comet up again, run the following from your `urbit` directory (note the lack of `-c` argument):

115

116```sh

117~/urbit/urbit mycomet

118```

119

120### Using Landscape

121

122Urbit is an entirely new computer, so by default it drops you into the "dojo," which is its terminal. Like your current computer, it can be used to do just about anything if you know the right commands. You only need to know one command for now.

123

124At the moment, the most common way to use Urbit is through a web app named [Landscape](/docs/glossary/landscape), which comes with Urbit. It runs in your browser and provides an interface to Urbit without using the terminal. You need to get the password, or `code`.

125

1261. With your Urbit running, 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. It will probably be 80, but we're just making sure. (Don't worry about the "insecure, public" part — that just means you can access it from your own web browser. It doesn't give anyone else access.)

1272. If the port given is `80`, simply type `localhost` into your browser's address bar. If the given port is a different number, such as `8080`, you would type `localhost:8080`. You'll be met with a login prompt.

1283. In the window where you found the port number, type `+code` and press return. Copy-paste the code that appears into the "Access Key" field in the browser, and press continue.

1294. Once in, take a look around and read the instructions on screen. If you ever get logged out, follow these instructions again.

130

131## Next Steps

132

133### Updating your comet {#updating}

134

135The Urbit application comes with a recent release of the Urbit OS, but automatic updates ("over the air") can be enabled so new binaries aren't necessary for each update. 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.

136

137You can enable updates for your comet by typing `|ota (sein:title our now our) %kids` into Dojo and pressing Enter.

138

139```

140> |ota (sein:title our now our) %kids

141>=

142```

143

144If you want to make sure you'll get updates, you can check by typing `|ota` with no arguments:

145

146```

147~sampel_marzod:dojo> |ota

148OTAs enabled from %kids on ~marzod

149use |ota %disable or |ota ~sponsor %kids to reset it

150> |ota

151>=

152```

153

154### Read More about the Dojo {#the-dojo}

155

156The dojo is Urbit's command line. You can use it to control your ship, or to execute arbitrary code. Check out the links below for more information.

157

158- [Basic Operations](/using/os/getting-started)

159- [Basic Hoon](/docs/tutorials/hoon/hoon-school/setup)

160- [Glossary Entry](/docs/glossary/dojo)

161

162### Purchase a Permanent Identity {#boot-your-planet}

163

164You can continue using this comet indefinitely. There are currently few differences between using a comet-level identity and a planet-level one. However, some groups will not allow comets entry in order to maintain a certain level of quality, and changes may be made in the future that further devalue comets. They will always, however, be able to access the basic functions of the network.

165

166A comet also comes with a long and fairly unmemorable name whereas a planet has a short name and a "sigil" (avatar) associated with it that makes it more identifiable on the network. You may notice all this within the first few minutes of using Urbit.

167

168[To read instructions on how to purchase and use a planet, visit this page](/getting-started/planet).

169

170<style>

171 .os {

172 display: flex;

173 flex-wrap: wrap;

174 }

175 .os label {

176 order: -1;

177 padding: .5rem;

178 min-width: 70px;