git.iko.soy/urbit.org
on e984eee help sign in
urbit.org/content/getting-started/cli.md
231 lines 7.5 kB history raw
1+++
2title = "Command line app"
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
8command line. This can be run on your local machine or a server in the cloud, we
9just cover the general case here.
11Note there is a much more comprehensive [cloud hosting
12guide](https://operators.urbit.org/manual/running/hosting) which walks through
13setting up Urbit on a [Digital Ocean](https://www.digitalocean.com/) VPS.
15### 1. Install Urbit
17Choose your operating system and run the given command in your terminal to
18download the Urbit runtime:
20{% tabs %}
22{% tab label="MacOS" %}
24```bash
25curl -L https://urbit.org/install/mac/latest | tar xzk --strip=1 && ./urbit
26```
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:
31> ```
32> /usr/sbin/softwareupdate --install-rosetta --agree-to-license
33> ```
35{% /tab %}
37{% tab label="Linux" %}
39```shell
40curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 && ./urbit
41```
43> Linux users may need to run this command in another terminal window to access
44> your urbit on port 80:
46> ```shell
47> sudo apt-get install libcap2-bin
48> sudo setcap 'cap_net_bind_service=+ep' ./urbit
49> ```
51{% /tab %}
53{% tab label="Windows" %}
55```winbatch
56curl -L https://urbit.org/install/windows/latest | tar -xzkf - --strip-components=1 && urbit
57```
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.
66{% /tab %}
68{% /tabs %}
70If successful, you will see a block of output beginning with the line:
72```
73Urbit: a personal server operating function
74```
76### 2. Boot Urbit
78An Urbit instance is intrinsically tied to a unique identity called an **Urbit
79ID**. There are five classes of Urbit ID, but we will consider two here: comets
80and planets.
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.
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.
96Follow the instructions for your case:
98{% tabs %}
100{% tab label="Boot a Comet" %}
102In the terminal, with the `urbit` binary you installed in the previous step, a
103comet can be booted with the `-c` option:
105```bash
106./urbit -c mycomet
107```
109> `mycomet` will be the name given to the data folder it will create. You can
110> choose any name you like.
112It may take a while to initialize the comet (usually only a couple of minutes,
113but it could take longer). When it's done, it'll take you to the dojo prompt
114(the dojo is Urbit's shell):
116```
117ames: live on 31337
118http: web interface live on http://localhost:8080
119http: loopback live on http://localhost:12321
120~sampel_marzod:dojo>
121```
123You 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
125folder, so you can start it up again by doing:
127```bash
128./mycomet/.run
129```
131Since comets are often used temporarily and then discarded, kernel updates are
132not enabled by default. If you plan to use your comet for a while, it's a good
133idea to enable updates with the following command in the dojo:
135```
136|ota (sein:title our now our)
137```
139Lastly, while the dojo is quite powerful, most people use their urbit via
140Landscape, the browser-based UI. In order to access Landscape, you need your web
141login code. You can get this by running the following command in the dojo:
143```
144+code
145```
147It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.
148Copy the code it gives you to the clipboard.
150{% /tab %}
152{% tab label="Boot a Planet" %}
154In order to boot a planet, you need a copy of its private keys. If you got your
155planet via a claim link, the passport backup `.zip` file you downloaded will
156contain a file called something like `sampel-palnet-1.key`. If you don't have
157the passport backup or you got your planet by another method, you can instead
158login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS
159section, and hit the "Download Keyfile" button.
161Back in the terminal, with the `urbit` binary you installed in the previous
162step, you can boot your planet with the following command (replacing
163`sampel-palnet` with your own planet and pointing to the location of your
164keyfile):
166```bash
167./urbit -w sampel-palnet -k sampel-palnet-1.key
168```
170This will create a data folder with the name of your planet and begin booting.
171It may take a while to initialize the planet (usually only a couple of minutes,
172but it could take longer). When it's done, it'll take you to the dojo prompt
173(the dojo is Urbit's shell):
175```
176ames: live on 31337
177http: web interface live on http://localhost:8080
178http: loopback live on http://localhost:12321
179~sampel-palnet:dojo>
180```
182You 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
184folder, so you can start it up again by doing:
186```bash
187./sampel-palnet/.run
188```
190While the dojo is quite powerful, most people use their urbit via Landscape, the
191browser-based UI. In order to access Landscape, you need your web login code.
192You can get this by running the following command in the dojo:
194```
195+code
196```
198It'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
200to the clipboard.
202One last thing: The `sampel-palnet-1.key` keyfile is only needed once, when you
203first boot your planet. Now that it's booted, it's good security practice to
204delete that keyfile.
206{% /tab %}
208{% /tabs %}
210### 3. Login
212While your urbit is running, the web interface called *Landscape* can be
213accessed 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
215at the boot messages in the terminal. You should see a line like:
217```
218http: web interface live on http://localhost:8080
219```
221Whichever address and port it says there is the one to open in the browser.
223Once open, you'll be presented with the login screen. Paste in the web login
224code you copied from the dojo in the previous step and hit "continue". You'll
225now be taken to your homescreen, with tiles for the default apps such as Groups
226and Terminal.
228### Next steps
230Learn how to [get around your
231urbit](https://urbit.org/getting-started/getting-around).