@@ -42,19 +42,17 @@ Once you've followed the appropriate install instructions, you can check if ever
4242Urbit: a personal server operating function
4343```
4444
45−### macOS
45+### macOS and Linux
4646
4747```sh
48+#macOS:
4849mkdir urbit
4950cd urbit
5051curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
5152tar xzf urbit-v0.10.8-darwin.tgz
5253./urbit-v0.10.8-darwin/urbit
53−```
54−
55−### Linux (64-bit)
5654
57−```sh
55+#Linux:
5856mkdir urbit
5957cd urbit
6058curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
@@ -63,7 +61,6 @@ tar xzf urbit-v0.10.8-linux64.tgz
6361```
6462
6563To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
66−
6764```sh
6865sudo apt-get install libcap2-bin
6966sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
@@ -72,11 +69,17 @@ sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
7269
7370### Windows
7471
75−> 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. These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
72+> 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.
73+
74+These instructions have been tested and verified for WSL 2 + Ubuntu 18.04 LTS.
75+
76+Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the [Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) on Windows 10.
7677
77−Urbit cannot run on Windows itself, but there is a convenient way to run a Linux distro using the [Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) on Windows 10. For Urbit to work, it is necessary to [install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and not just WSL.
78+For Urbit to work, it is necessary to [install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and not just WSL.
7879
79−Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Linux installation instructions above. For 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, by typing `cd ~`.
80+Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Linux installation instructions above.
81+
82+For 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, by typing `cd ~`.
8083
8184## Launching Urbit
8285
@@ -98,13 +101,17 @@ Comets are disposable, free identities that can be used to quickly join the netw
98101
99102### Booting a comet
100103
101−To boot a comet, go into the command line and run the following command from the urbit directory you created during Urbit installation:
104+To boot a comet, go into the command line and run the following command from the `urbit` directory you created during Urbit installation:
102105
103106```sh
104−$ ./urbit-v0.10.8-darwin/urbit -c mycomet
107+#macOS:
108+./urbit-v0.10.8-darwin/urbit -c mycomet
109+
110+#Linux:
111+./urbit-v0.10.8-linux64/urbit -c mycomet
105112```
106113
107−This will take up to an hour, and will spin out a bunch of boot messages. It will also create a directory called `mycomet` in the Unix directory that you ran the command from (which should be your urbit directory).
114+This will take up to an hour, and will spin out a bunch of boot messages. It will also create a directory called `mycomet` in the Unix directory that you ran the command from (which should be your `urbit` directory).
108115
109116Toward the end of the boot process, you'll see something like:
110117
@@ -116,11 +123,18 @@ http: live (insecure, loopback) on 12321
116123~sampel_commet:dojo>
117124```
118125
119−When your ship is finished booting, you will see either the `~sampel_commet:dojo>` or `~sampel_commet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo.
126+When your ship is finished booting, you will see either the `~sampel_commet:dojo>` or `~sampel_commet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-X` to switch into Dojo.
127+
128+To exit Urbit, use `Ctrl-D` or enter `|exit` into Dojo.
120129
121−To exit Urbit, use `Ctrl-d`.
130+To start your ship up again, run the following from your `urbit` directory (note the lack of `-c` argument):
131+```sh
132+#macOS:
133+./urbit-v0.10.8-darwin/urbit mycomet
122134
123−To start your ship up again, run `./urbit-v0.10.8-darwin/urbit mycomet` from your `urbit` directory.
135+#Linux:
136+./urbit-v0.10.8-linux64/urbit mycomet
137+```
124138
125139### The Dojo
126140
@@ -225,30 +239,58 @@ Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
225239
226240#### Step 3: Run the boot command
227241
228−If you are not already within the directory you installed above, enter it by running `cd urbit-v0.10.8-darwin` (for Mac) or `cd urbit-v0.10.8-linux64` (for Linux) from where you ran the install commands. It contains your Urbit binary, and your ship will be installed here as well.
242+Enter your `urbit` directory.
229243
230244Once you're inside, run the command below, except with `sampel-palnet` replaced by the name of your
231245Urbit identity, and `path/to/my-planet.key` replaced with the path to your keyfile:
232246
233247```sh
234−./urbit -w sampel-palnet -k path/to/my-planet.key
248+#macOS:
249+./urbit-v0.10.8-darwin/urbit -w sampel-palnet -k path/to/my-planet.key
250+
251+#Linux:
252+./urbit-v0.10.8-linux64/urbit -w sampel-palnet -k path/to/my-planet.key
235253```
236254
237255Or, if you'd prefer to copy your key in, you can run:
238256
239257```sh
240−./urbit -w sampel-palnet -G rAnDoMkEy
258+#macOS:
259+./urbit-v0.10.8-darwin/urbit -w sampel-palnet -G rAnDoMkEy
260+
261+#Linux:
262+./urbit-v0.10.8-linux64/urbit -w sampel-palnet -G rAnDoMkEy
241263```
242264
243265Either command will create a directory called `sampel-palnet/` and begin building your ship. It may take a few minutes.
244266
245−When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
267+When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-X` to switch into Dojo.
268+
269+To shut down your ship, use `Ctrl-D`. To start your ship up again, run the following from your `urbit` directory:
246270
247−To shut down your ship, use `Ctrl-d`. To start your ship up again, run `./urbit sampel-palnet/` from the directory where your Urbit binary is saved. Note that in this usage, `sampel-palnet/` is the path of a folder, which by default is located in the same folder as the Urbit binary. This folder is called your ship's **pier**, and you can put it wherever you like.
271+```sh
272+#macOS:
273+./urbit-v0.10.8-darwin/urbit sampel-palnet
274+
275+#Linux:
276+./urbit-v0.10.8-linux64/urbit sampel-palnet
277+```
278+
279+Note that `sampel-palnet/` is the path of a folder, which we just created in your `urbit` directory. This folder is called your ship's **pier**.
248280
249281Never boot multiple instances of your ship at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
250282
251−**Important:** once a key has been used to boot a ship onto the network, it cannot be used to boot that ship again later - doing so will cause communication problems with other ships. For this reason you should **delete the keyfile from your machine once your ship has booted successfully**. (If you do use the same key twice, you'll need to conduct a [personal breach](#breaches) to restore your ship to full functionality).
283+**Important:** once a key has been used to boot a ship onto the network, it cannot be used to boot that ship again later - doing so will cause communication problems with other ships.
284+
285+For this reason you should **delete the keyfile from your machine once your ship has booted successfully**.
286+
287+If you do use the same key twice, you'll need to conduct a [personal breach](#breaches) to restore your ship to full functionality).
288+
289+Delete the keyfile with the command below:
290+
291+```sh
292+rm path/to/my-planet.key
293+```
252294
253295### Updating to the latest binary
254296
@@ -256,34 +298,48 @@ Most updates to Urbit are downloaded and applied automatically as OTA (Over the
256298
257299To update to the latest binary, download and extract it to replace your existing one. Then run it as before.
258300
259−For example, if in your current `urbit` directory you have an `urbit-v0.10.7-darwin` directory along with a ship directory called `mycomet`, and a new `urbit-v0.10.8-darwin` binary was just released, then you'd run the following commands from your `urbit` directory (the example commands below use the darwin installer, but you should use the one for your OS):
301+For example, if in your current `urbit` directory you have an `urbit-v0.10.7-<OS>` directory along with a ship directory called `mycomet`, and a new `urbit-v0.10.8-<OS>` binary was just released, then you'd run the following commands from your `urbit` directory:
260302
261−First shut down your ship, by running the following in dojo (or control-d).
303+First shut down your ship, by running the following in dojo (or `Ctrl-D`).
262304```
263305|exit
264306```
265307
266−Next download and extract the most recent binary from inside your `urbit` directory:
267−```
268−curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
269−tar xzf urbit-v0.10.8-darwin.tgz
270−```
308+**NOTE**: Your ship itself can be reused, only the binary needs to be changed. This is why we have the directory structure configured as an `urbit` directory that contains your ship and your binary. This structure makes it easy to swap in new binaries. If you have your ship *inside* the `urbit-vX.XX.X` directory, move it out before deleting that directory.
271309
272310Delete the old binary directory from your `urbit` directory:
273311
274−**NOTE**: Your ship itself can be reused, only the binary needs to be changed. This is why we have the directory structure configured as an urbit directory that contains your ship and your binary. This structure makes it easy to swap in new binaries. If you have your ship *inside* the `urbit-vX.XX.X` directory, move it out before deleting that directory.
275−```
312+```sh
313+#macOS:
276314rm -rf urbit-v0.10.7-darwin
315+
316+#Linux:
317+rm -rf urbit-v0.10.7-linux64
277318```
278319
279−Start up your ship with the new binary from your `urbit` directory:
320+Next download and extract the most recent binary from inside your `urbit` directory:
321+```sh
322+#macOS:
323+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
324+tar xzf urbit-v0.10.8-darwin.tgz
325+
326+#Linux:
327+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
328+tar xzf urbit-v0.10.8-linux64.tgz
280329```
330+
331+Start up your ship with the new binary from your `urbit` directory:
332+```sh
333+#macOS:
281334./urbit-v0.10.8-darwin/urbit mycomet
335+
336+#Linux:
337+./urbit-v0.10.8-linux64/urbit mycomet
282338```
283339
284340Then you're good to go, in the future you'll just modify the version numbers in the example above to the most recent version.
285341
286−### Breaches
342+### Breaches {#breaches}
287343
288344An important concept on the Urbit network is that of continuity. Continuity refers to how ships remember the order of their own network messages and the network messages of others -- these messages are numbered, starting from zero. A breach is when ships on the network agree to forget about this sequence and treat one or more ships like they are brand new.
289345