git.iko.soy/urbit.org
on b37d6e5 help sign in
urbit.org/content/getting-started/cli.md
226 lines 7.4 kB history raw
1+++
2title = "Command line install"
3weight = 4
4description = "Installation instructions for power users."
5tag = "additional"
6+++
8If you're a power user, you can run the Urbit virtual machine directly using the
9command line. This can be run on your local machine or a server in the cloud, we
10just cover the general case here.
12Note there is a much more comprehensive [cloud hosting
13guide](https://operators.urbit.org/manual/running/hosting) which walks through
14setting up Urbit on a [Digital Ocean](https://www.digitalocean.com/) VPS.
16## 1. Install Urbit
18Choose your operating system and run the given command in your terminal to
19download the Urbit runtime:
21{% tabs %}
23{% tab label="MacOS" %}
25```bash
26curl -L https://urbit.org/install/mac/latest | tar xzk --strip=1 && ./urbit
27```
29> Note our Mac build is only compatible with Apple Silicon (M1/M2) via Rosetta.
30> If you have such a machine you may need to run the following command:
32> ```
33> /usr/sbin/softwareupdate --install-rosetta --agree-to-license
34> ```
36{% /tab %}
38{% tab label="Linux" %}
40```shell
41curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 && ./urbit
42```
44> Linux users may need to run this command in another terminal window to access
45> your Urbit on port 80:
47> ```shell
48> sudo apt-get install libcap2-bin
49> sudo setcap 'cap_net_bind_service=+ep' ./urbit
50> ```
52{% /tab %}
54{% tab label="Windows" %}
56```winbatch
57curl -L https://urbit.org/install/windows/latest | tar -xzkf - --strip-components=1 && urbit
58```
60> Windows 10 build 17063 and later includes the familiar `curl` and `tar`
61> command-line tools. If you're running an older version of Windows, you may need
62> to visit
63> [https://github.com/urbit/urbit/releases/latest](https://github.com/urbit/urbit/releases/latest)
64> in the browser, download the `windows.zip` file, extract it and execute the
65> contained `urbit.exe` file in the command prompt.
67{% /tab %}
69{% /tabs %}
71If successful, you will see a block of output beginning with the line:
73```
74Urbit: a personal server operating function
75```
77## 2. Boot Urbit
79An Urbit instance is intrinsically tied to a unique identity called an **Urbit
80ID**. There are five classes of Urbit ID, but we will consider two here: comets
81and planets.
83- **Comet:** A comet is an identity which anyone can generate themselves, for
84 free. It's a good option to try out Urbit. Comets are limited by the fact they
85 cannot be "factory reset", meaning if your Urbit somehow becomes broken or
86 corrupted then you'll have to start again with a new identity. In that sense,
87 they are impermanent.
89- **Planet:** A planet is a permanent identity which you own forever. Planets
90 are the class intended for individuals. While there are essentially an
91 unlimited number of comets, planets are more scarce (preventing spamming,
92 among other things). This scarcity means they usually aren't free (though
93 sometimes nice people give them away). This guide will assume you've already
94 acquired a planet. If you haven't, you can refer to the ["Get a planet"
95 guide](https://urbit.org/getting-started/get-planet) before continuing.
97Follow the instructions for your case:
99{% tabs %}
101{% tab label="Boot a Comet" %}
103In the terminal, with the `urbit` binary you installed in the previous step, a
104comet can be booted with the `-c` option:
106```bash
107./urbit -c mycomet
108```
110> `mycomet` will be the name given to the data folder it will create. You can
111> choose any name you like.
113It may take a while to initialize the comet (usually only a couple of minutes,
114but it could take longer). When it's done, it'll take you to the dojo prompt
115(the dojo is Urbit's shell):
117```
118ames: live on 31337
119http: web interface live on http://localhost:8080
120http: loopback live on http://localhost:12321
121~sampel_marzod:dojo>
122```
124You can shut down the comet again by typing `|exit` in the dojo or hitting
125`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data
126folder, so you can start it up again by doing:
128```bash
129./mycomet/.run
130```
132Since comets are often used temporarily and then discarded, kernel updates are
133not enabled by default. If you plan to use your comet for a while, it's a good
134idea to enable updates with the following command in the dojo:
136```
137|ota (sein:title our now our)
138```
140Lastly, while the dojo is quite powerful, most people use their Urbit via
141Landscape, the browser-based UI. In order to access Landscape, you need your web
142login code. You can get this by running the following command in the dojo:
144```
145+code
146```
148It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.
149Copy the code it gives you to the clipboard.
151{% /tab %}
153{% tab label="Boot a Planet" %}
155In order to boot a planet, you need a copy of its private keys. If you got your
156planet via a claim link, the passport backup `.zip` file you downloaded will
157contain a file called something like `sampel-palnet-1.key`. If you don't have
158the passport backup or you got your planet by another method, you can instead
159login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS
160section, and hit the "Download Keyfile" button.
162Back in the terminal, with the `urbit` binary you installed in the previous
163step, you can boot your planet with the following command (replacing
164`sampel-palnet` with your own planet and pointing to the location of your
165keyfile):
167```bash
168./urbit -w sampel-palnet -k sampel-palnet-1.key
169```
171This will create a data folder with the name of your planet and begin booting.
172It may take a while to initialize the planet (usually only a couple of minutes,
173but it could take longer). When it's done, it'll take you to the dojo prompt
174(the dojo is Urbit's shell):
176```
177ames: live on 31337
178http: web interface live on http://localhost:8080
179http: loopback live on http://localhost:12321
180~sampel-palnet:dojo>
181```
183You can shut down the planet again by typing `|exit` in the dojo or hitting
184`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data
185folder, so you can start it up again by doing:
187```bash
188./sampel-palnet/.run
189```
191While the dojo is quite powerful, most people use their Urbit via Landscape, the
192browser-based UI. In order to access Landscape, you need your web login code.
193You can get this by running the following command in the dojo:
195```
196+code
197```
199It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`
200(note this is a separate code to your master ticket). Copy the code it gives you
201to the clipboard.
203{% /tab %}
205{% /tabs %}
207## 3. Login to Landscape
209While your Urbit is running, the web interface called *Landscape* can be
210accessed in the browser. Its URL will usually be either `localhost` or
211`localhost:8080`, depending on your platform. To check the address, you can look
212at the boot messages in the terminal. You should see a line like:
214```
215http: web interface live on http://localhost:8080
216```
218Whichever address and port it says there is the one to open in the browser.
220Once open, you'll be presented with the login screen. Paste in the web login
221code you copied from the dojo in the previous step and hit "continue". You'll
222now be taken to your homescreen, with tiles for the default apps such as Groups
223and Terminal.
225For more information on navigating Landscape, see the [getting
226around](https://urbit.org/getting-started/getting-around) guide.