@@ -1,11 +1,21 @@
11+++
2−title = "Command line install"
3−weight = 4
2+title = "Command line app"
3+weight = 2
44description = "Installation instructions for power users."
5−tag = "additional"
65+++
76
8−If 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.
7+If you're a power user, you can run the Urbit virtual machine directly using the
8+command line. This can be run on your local machine or a server in the cloud, we
9+just cover the general case here.
10+
11+Note there is a much more comprehensive [cloud hosting
12+guide](https://operators.urbit.org/manual/running/hosting) which walks through
13+setting up Urbit on a [Digital Ocean](https://www.digitalocean.com/) VPS.
14+
15+### 1. Install Urbit
16+
17+Choose your operating system and run the given command in your terminal to
18+download the Urbit runtime:
919
1020{% tabs %}
1121
@@ -15,12 +25,12 @@ If you're a power user, you can run the Urbit virtual machine directly using the
1525curl -L https://urbit.org/install/mac/latest | tar xzk --strip=1 && ./urbit
1626```
1727
18−Note our Mac build is only compatible with Apple Silicon (M1/M2) via Rosetta.
19−If you have such a machine you must run the following command:
20−
21−```
22−/usr/sbin/softwareupdate --install-rosetta --agree-to-license
23−```
28+> Note our Mac build is only compatible with Apple Silicon (M1/M2) via Rosetta.
29+> If you have such a machine you may need to run the following command:
30+>
31+> ```
32+> /usr/sbin/softwareupdate --install-rosetta --agree-to-license
33+> ```
2434
2535{% /tab %}
2636
@@ -30,12 +40,13 @@ If you have such a machine you must run the following command:
3040curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 && ./urbit
3141```
3242
33−Linux users may need to run this command in another terminal window to access your Urbit on port 80:
34−
35−```shell
36−sudo apt-get install libcap2-bin
37−sudo setcap 'cap_net_bind_service=+ep' ./urbit
38−```
43+> Linux users may need to run this command in another terminal window to access
44+> your urbit on port 80:
45+>
46+> ```shell
47+> sudo apt-get install libcap2-bin
48+> sudo setcap 'cap_net_bind_service=+ep' ./urbit
49+> ```
3950
4051{% /tab %}
4152
@@ -45,12 +56,12 @@ sudo setcap 'cap_net_bind_service=+ep' ./urbit
4556curl -L https://urbit.org/install/windows/latest | tar -xzkf - --strip-components=1 && urbit
4657```
4758
48−Windows 10 build 17063 and later includes the familiar `curl` and `tar`
49−command-line tools. If you're running an older version of Windows, you may need
50−to visit
51−[https://github.com/urbit/urbit/releases/latest](https://github.com/urbit/urbit/releases/latest)
52−in the browser, download the `windows.zip` file, extract it and execute the
53−contained `urbit.exe` file in the command prompt.
59+> Windows 10 build 17063 and later includes the familiar `curl` and `tar`
60+> command-line tools. If you're running an older version of Windows, you may need
61+> to visit
62+> [https://github.com/urbit/urbit/releases/latest](https://github.com/urbit/urbit/releases/latest)
63+> in the browser, download the `windows.zip` file, extract it and execute the
64+> contained `urbit.exe` file in the command prompt.
5465
5566{% /tab %}
5667
@@ -62,99 +73,159 @@ If successful, you will see a block of output beginning with the line:
6273Urbit: a personal server operating function
6374```
6475
65−### Booting a free identity {% #comet %}
76+### 2. Boot Urbit
6677
67−There are two parts to Urbit: an **ID** and an **Operating System**.
78+An Urbit instance is intrinsically tied to a unique identity called an **Urbit
79+ID**. There are five classes of Urbit ID, but we will consider two here: comets
80+and planets.
6881
69−You have just installed the Operating System on your computer.
82+- **Comet:** A comet is an identity which anyone can generate themselves, for
83+ free. It's a good option to try out Urbit. Comets are limited by the fact they
84+ cannot be "factory reset", meaning if your urbit somehow becomes broken or
85+ corrupted then you'll have to start again with a new identity. In that sense,
86+ they are impermanent.
7087
71−The **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.
88+- **Planet:** A planet is a permanent identity which you own forever. Planets
89+ are the class intended for individuals. While there are essentially an
90+ unlimited number of comets, planets are more scarce (preventing spamming,
91+ among other things). This scarcity means they usually aren't free (though
92+ sometimes nice people give them away). This guide will assume you've already
93+ acquired a planet. If you haven't, you can refer to the ["Get a planet"
94+ guide](https://urbit.org/getting-started/get-planet) before continuing.
7295
73−There are five kinds of Urbit IDs but to get started you only need to know about two: we call them **planets** and **comets**.
96+Follow the instructions for your case:
7497
75−---
98+{% tabs %}
7699
77−**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.
100+{% tab label="Boot a Comet" %}
78101
79−A planet name looks like `~sampel-palnet`.
102+In the terminal, with the `urbit` binary you installed in the previous step, a
103+comet can be booted with the `-c` option:
80104
81−[Follow this guide](/getting-started/) if you have already acquired a planet.
105+```bash
106+./urbit -c mycomet
107+```
82108
83−[Find a planet to purchase](/getting-started/get-planet)
109+> `mycomet` will be the name given to the data folder it will create. You can
110+> choose any name you like.
84111
85−---
112+It may take a while to initialize the comet (usually only a couple of minutes,
113+but it could take longer). When it's done, it'll take you to the dojo prompt
114+(the dojo is Urbit's shell):
86115
87−**Comets** are practically unlimited and free to acquire. At present, these are a great way to try out the network for free.
116+```
117+ames: live on 31337
118+http: web interface live on http://localhost:8080
119+http: loopback live on http://localhost:12321
120+~sampel_marzod:dojo>
121+```
88122
89−A comet name looks like `~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`.
123+You can shut down the comet again by typing `|exit` in the dojo or hitting
124+`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data
125+folder, so you can start it up again by doing:
90126
91−[Read more about Urbit ID here](/understanding-urbit/urbit-id)
127+```bash
128+./mycomet/.run
129+```
92130
93−---
131+Since comets are often used temporarily and then discarded, kernel updates are
132+not enabled by default. If you plan to use your comet for a while, it's a good
133+idea to enable updates with the following command in the dojo:
94134
95−To boot a comet, go into the command line and run the following command:
135+```
136+|ota (sein:title our now our)
137+```
96138
97−```sh
98−./urbit -c mycomet
139+Lastly, while the dojo is quite powerful, most people use their urbit via
140+Landscape, the browser-based UI. In order to access Landscape, you need your web
141+login code. You can get this by running the following command in the dojo:
142+
143+```
144++code
145+```
146+
147+It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.
148+Copy the code it gives you to the clipboard.
149+
150+{% /tab %}
151+
152+{% tab label="Boot a Planet" %}
153+
154+In order to boot a planet, you need a copy of its private keys. If you got your
155+planet via a claim link, the passport backup `.zip` file you downloaded will
156+contain a file called something like `sampel-palnet-1.key`. If you don't have
157+the passport backup or you got your planet by another method, you can instead
158+login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS
159+section, and hit the "Download Keyfile" button.
160+
161+Back in the terminal, with the `urbit` binary you installed in the previous
162+step, you can boot your planet with the following command (replacing
163+`sampel-palnet` with your own planet and pointing to the location of your
164+keyfile):
165+
166+```bash
167+./urbit -w sampel-palnet -k sampel-palnet-1.key
99168```
100169
101−It 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:
170+This will create a data folder with the name of your planet and begin booting.
171+It may take a while to initialize the planet (usually only a couple of minutes,
172+but it could take longer). When it's done, it'll take you to the dojo prompt
173+(the dojo is Urbit's shell):
102174
103175```
104176ames: live on 31337
105177http: web interface live on http://localhost:8080
106178http: loopback live on http://localhost:12321
107−~sampel_marzod:dojo>
179+~sampel-palnet:dojo>
108180```
109181
110−When your comet is finished booting, you will see `~sampel_marzod:dojo>` (Dojo: the Urbit command line).
182+You can shut down the planet again by typing `|exit` in the dojo or hitting
183+`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data
184+folder, so you can start it up again by doing:
111185
112−To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
113−
114−To start your comet up again, run the following command:
115−
116−```sh
117−./mycomet/.run
186+```bash
187+./sampel-palnet/.run
118188```
119189
120−### Using the web interface
190+While the dojo is quite powerful, most people use their urbit via Landscape, the
191+browser-based UI. In order to access Landscape, you need your web login code.
192+You can get this by running the following command in the dojo:
121193
122−Urbit 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.
194+```
195++code
196+```
123197
124−At the moment, the most common way to use Urbit is by launching apps like Groups (a communications suite) from the web interface homescreen. The web interface allows you to use your ship without touching the terminal. You just need to get the password, or `code`, from the terminal.
198+It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`
199+(note this is a separate code to your master ticket). Copy the code it gives you
200+to the clipboard.
125201
126−1. With your Urbit running, look for a line that says something like `http: web interface live on http://localhost:8080`. The number given is the port that your ship is using. It will most likely be 80 or 8080, but we're just making sure.
127−2. 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.
128−3. 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.
129−4. Once in, take a look around and try launching an app like Groups.
202+One last thing: The `sampel-palnet-1.key` keyfile is only needed once, when you
203+first boot your planet. Now that it's booted, it's good security practice to
204+delete that keyfile.
130205
131−## Next Steps
206+{% /tab %}
132207
133−### Updating your comet {% #updating %}
208+{% /tabs %}
134209
135−Urbit comes with a recent release of the Urbit OS, but automatic updates of the `%base` desk (which contains the kernel of the OS) are not enabled by default 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.
210+### 3. Login
136211
137−You can enable updates for your comet by typing `|ota (sein:title our now our)` into Dojo and pressing Enter.
212+While your urbit is running, the web interface called *Landscape* can be
213+accessed in the browser. Its URL will usually be either `localhost` or
214+`localhost:8080`, depending on your platform. To check the address, you can look
215+at the boot messages in the terminal. You should see a line like:
138216
139217```
140−> |ota (sein:title our now our)
141−>=
142−kiln: activated install into %base from [~samzod %kids]
143−kiln: downloading update for %base from [~samzod %kids]
218+http: web interface live on http://localhost:8080
144219```
145220
146−### Read More about the Dojo {% #the-dojo %}
147−
148−The 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.
149−
150−- [Basic Operations](/using/os/getting-started)
151−- [Basic Hoon](/docs/tutorials/hoon/hoon-school/setup)
152−- [Glossary Entry](/docs/glossary/dojo)
153−
154−### Purchase a Permanent Identity {% #boot-your-planet %}
221+Whichever address and port it says there is the one to open in the browser.
155222
156−You 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.
223+Once open, you'll be presented with the login screen. Paste in the web login
224+code you copied from the dojo in the previous step and hit "continue". You'll
225+now be taken to your homescreen, with tiles for the default apps such as Groups
226+and Terminal.
157227
158−A 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.
228+### Next steps
159229
160−[For details of how to purchase a planet, visit this page](/getting-started/get-planet).
230+Learn how to [get around your
231+urbit](https://urbit.org/getting-started/getting-around).