@@ -10,11 +10,17 @@ Urbit is not yet ready for everyday users — but if you're technically inclined
1010
1111In order to get going on the network, you'll need an [Urbit ID](#id). To try the live network out with a disposable identity, you can always [create a comet](@/using/operations/creating-a-comet.md).
1212
13−## Getting an Urbit ID {#id}
13+## Urbit ID: An Overview {#id}
1414
15−For an introduction to Urbit IDs and the address space more generally, see [Urbit ID](@/understanding-urbit/urbit-id.md) in [Understanding Urbit](@/understanding-urbit/_index.md).
15+Urbit works as a peer-to-peer network where fail because peers -- called **ships** -- are all associated with persistent and scarce identities that we refer to as **Urbit ID**. The Urbit ID registry is deployed on the Ethereum blockchain, and individual IDs exist as non-fungible tokens in that cryptographic ecosystem that chain.
1616
17−While Tlon does not currently sell or distribute Urbit IDs, there are still a few ways to get your own Urbit ID:
17+Urbit IDs function as network addresses, represented by pronounceable names like `~padmyn-pasnux`. There are a few kinds of Urbit ID, but ones meant for typical users are called **planets**. Anyone who has a planet can be thought of as a full "citizen" of the Urbit network.
18+
19+But sometimes a user might not want a persistent identity for whatever reason. In that case, they can use Urbit without an Urbit ID by using something called called a **comet**. Comets can be spun up at will and for free. They are good for bots and for people who are new to Urbit and want to check out the network.
20+
21+For a more in-depth explanation of Urbit ID and the address space more generally, see the [Urbit ID](@/understanding-urbit/urbit-id.md) essay in [Understanding Urbit](@/understanding-urbit/_index.md).
22+
23+Tlon doesn't currently sell or distribute Urbit IDs, but there are a few ways to get your own:
1824
1925- Getting an invitation from a friend
2026- Purchasing an Urbit ID from a third party, such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), or [Urbit Marketplace](https://urbitmarketplace.com/).
@@ -23,18 +29,36 @@ Tlon occasionally selects candidates to distribute invitations, and users operat
2329
2430## Using your Urbit ID
2531
26−If you have an Urbit ID, you'll use [Bridge](https://bridge.urbit.org) to get your ship's keyfile before you can [boot your ship](#booting-your-ship). For more information on how to use Bridge, see [Using Bridge](@/using/operations/using-bridge.md).
32+If you have an Urbit ID, you'll use the [Bridge](https://bridge.urbit.org) client to get your ship's *keyfile* before you can [boot your ship](#booting-your-ship). Your keyfile is a cryptographic secret that allows your Urbit instance to authenticate itself on the network, so you can't boot your planet without it. Your keyfile is deterministically derived from your other cryptographic secrets.
2733
28−## Install Urbit {#urbit}
34+### The Urbit ID Wallet
35+
36+Your Urbit ID is actually yours. As long as you control the cryptographic secrets, nobody can take it away from you. That's why it's important to know a little bit.
37+
38+Urbit ID secrets operate as a system of separate but hierarchically realted Ethereum key-pairs. For any given ID, this system of key-pairs is referred to as a **Hierarchical Deterministic (HD) Wallet**. the Urbit HD wallet. Each of these Ethereum addresses have different powers over the same identity, from setting networking keys for communicating in the Arvo network to transferring ownership of identities. Important elements of the HD wallet:
39+
40+- **Master Ticket**: The "password" at the top of the hierarchy that determines the ownership. All other secrets are derived from this. If the rest of the wallet is lost or compromised, the master ticket can rederive everything. You'll log into Bridge with this. Always keep your master ticket extremely safe.
41+
42+- **Management Proxy**: Derived from the master ticket. Can perform non-ownership related operations such as configuring Arvo networking keys.
43+
44+- **Keyfile**: Derived from the management proxy. Used as crytopgraphic proof that your Urbit ship it is who it says it is. You use it to start up your ship for the first time.
2945
30−The Urbit binary runs nicely on a Unix-like operating system – Ubuntu, Fedora, or macOS, for example. If you're using Windows, you'll need to get one of the aforementioned systems. But first, some terminology:
46+### Getting Your Keyfile
3147
32−- `vere` or `urbit`: the interpreter that runs when you run a command like `./urbit` in your command line
33−- `arvo`: the deterministic OS that lives in a directory whose name matches your Urbit ID, i.e. `~famreb-todmec` lives in `/famreb-todmec`
48+As mentioned previously, there are a few ways to acquire a planet. All methods, however, should result in you receiving at least one secret, such as a **master ticket**. If you received an email invite to Urbit, the master ticket should a `.pdf` the passport folder that you downloaded.
49+
50+1. To connect to Bridge, go to https://bridge.urbit.org.
51+2. Enter the name of you planet and the associated master ticket in the appropriate fields. If you received your secret is in another form, such as a dictionary mnemonic, click the `Metamask, Mnemonic, Hardware Wallet...` button for alternate login methods.
52+3. Once you're logged in, click the `OS` option.
53+4. In resulting page, click the `Download Arvo Keyfile` button. You should receive a `.key` file that contains the secret needed to boot your ship. Hold on to this file.
54+
55+## Install Urbit {#urbit}
56+
57+The Urbit binary runs on a Unix-like operating system – Ubuntu, Fedora, or macOS, for example. If you're using Windows, you'll need to get one of the aforementioned systems. But first, some terminology:
3458
3559We have different installation instructions for different platforms. To install and run Arvo, the Urbit operating system, and its binary, run the commands that are listed for your operating system.
3660
37−You can check your Arvo installation on any platform by running the `./urbit` command. Installation was successful if you get a block of output that begins with the line below:
61+Once you've followed the appropriate install instructions, you can check if everythign went right by running the `./urbit` command. Installation was successful if you get a block of output that begins with the line below:
3862
3963```
4064Urbit: a personal server operating function
@@ -42,8 +66,6 @@ Urbit: a personal server operating function
4266
4367### macOS
4468
45−We provide static binaries for macOS. You can grab the latest stable release as follows:
46−
4769```sh
4870curl -O https://bootstrap.urbit.org/urbit-v0.10.7-darwin.tgz
4971tar xzf urbit-v0.10.7-darwin.tgz
@@ -53,8 +75,6 @@ cd urbit-v0.10.7-darwin
5375
5476### Linux (64-bit)
5577
56−We also provide static binaries for 64-bit Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). You can get the latest stable release similarly:
57−
5878```sh
5979curl -O https://bootstrap.urbit.org/urbit-v0.10.7-linux64.tgz
6080tar xzf urbit-v0.10.7-linux64.tgz
@@ -86,7 +106,7 @@ If you want to compile from source, see the [instructions on GitHub](https://git
86106
87107### About swap space
88108
89−If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, you can safely ignore this section.
109+If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, you can ignore this section.
90110
91111Urbit wants to map 2GB of memory when it boots up. It won’t necessarily use all this memory, it just wants to see it. On a normal modern PC or Mac, or on a large cloud virtual machine, this is not an issue. On some small cloud virtual machines (Amazon or Digital Ocean) the default memory configuration is smaller than this, and you need to manually configure a swapfile.
92112
@@ -94,7 +114,7 @@ Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/comm
94114
95115## Booting your ship {#booting-your-ship}
96116
97−Now the rubber meets the road. You'll be booting your ship with the keyfile that you [downloaded from Bridge](@/using/operations/using-bridge.md).
117+Now the rubber meets the road. You'll be booting your ship with the keyfile that you downloaded from Bridge [earlier in this document](#id).
98118
99119Note that this section is only for booting a ship that uses the live Arvo network. If you just want to create an unnetworked ship for development purposes, read [this guide](@/using/develop.md#creating-a-development-ship) instead.
100120
@@ -127,7 +147,7 @@ Either command will create a directory called `sampel-palnet/` and begin buildin
127147
128148When 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.
129149
130−To shut down your ship, use `Ctrl-d`.
150+To shut down your ship, use `Ctrl-d`.
131151
132152To start your ship up again, run `./urbit sampel-palnet/` from the directory
133153where your Urbit binary is saved. Note that in this usage,
@@ -174,14 +194,12 @@ Good, your Dojo is working correctly. Now let's run our first useful command in
174194
175195The `>=` output means that a command was successful. Now you can see your ship's files in its Unix directory.
176196
177−
178−
179197## Using Landscape
180198
181199Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. To get onto Landscape:
182200
1832011. Start your ship. In the boot messages, 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.
184−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`. Alternatively, you access landscape by navigating to `sampel-palnet.arvo.network` into your URL bar, where `sampel-palnet` is the name of your ship, without the `~`. You will need to [set up DNS proxying](@/using/operations/using-your-ship.md#dns-proxying) to use this option.
202+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`. Alternatively, you access landscape by navigating to `sampel-palnet.arvo.network` into your URL bar, where `sampel-palnet` is the name of your ship, without the `~`. You will need to [set up DNS proxying](@/using/operations/using-your-ship.md#dns-proxying) to use this option. To do so, simply run this command in your ship's Dojo: `> -dns-address &dns-address [%if .1.2.3.4]`, where `.1.2.3.4` is the IP address.
1852033. Type `+code` into your ship's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
1862044. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
187205