@@ -10,11 +10,17 @@ Urbit is not yet ready for everyday users — but if you're technically inclined
11In 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).
11In 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).
13−## Getting an Urbit ID {#id}
13+## Urbit ID: An Overview {#id}
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.
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.
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.
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).
17−While Tlon does not currently sell or distribute Urbit IDs, there are still a few ways to get your own Urbit ID:
23+Tlon doesn't currently sell or distribute Urbit IDs, but there are a few ways to get your own:
19- Getting an invitation from a friend
25- Getting an invitation from a friend
20- 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/).
26- 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
24## Using your Urbit ID
30## Using your Urbit ID
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.
28−## Install Urbit {#urbit}
34+### The Urbit ID Wallet
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.
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:
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.
42+- **Management Proxy**: Derived from the master ticket. Can perform non-ownership related operations such as configuring Arvo networking keys.
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.
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
32−- `vere` or `urbit`: the interpreter that runs when you run a command like `./urbit` in your command line
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.
33−- `arvo`: the deterministic OS that lives in a directory whose name matches your Urbit ID, i.e. `~famreb-todmec` lives in `/famreb-todmec`
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.
55+## Install Urbit {#urbit}
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:
35We 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.
59We 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.
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:
40Urbit: a personal server operating function
64Urbit: a personal server operating function
@@ -42,8 +66,6 @@ Urbit: a personal server operating function
45−We provide static binaries for macOS. You can grab the latest stable release as follows:
48curl -O https://bootstrap.urbit.org/urbit-v0.10.7-darwin.tgz
70curl -O https://bootstrap.urbit.org/urbit-v0.10.7-darwin.tgz
49tar xzf urbit-v0.10.7-darwin.tgz
71tar xzf urbit-v0.10.7-darwin.tgz
@@ -53,8 +75,6 @@ cd urbit-v0.10.7-darwin
54### Linux (64-bit)
76### Linux (64-bit)
56−We also provide static binaries for 64-bit Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). You can get the latest stable release similarly:
59curl -O https://bootstrap.urbit.org/urbit-v0.10.7-linux64.tgz
79curl -O https://bootstrap.urbit.org/urbit-v0.10.7-linux64.tgz
60tar xzf urbit-v0.10.7-linux64.tgz
80tar 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
87### About swap space
107### About swap space
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.
91Urbit 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.
111Urbit 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.
@@ -94,7 +114,7 @@ Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/comm
95## Booting your ship {#booting-your-ship}
115## Booting your ship {#booting-your-ship}
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).
99Note 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.
119Note 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.
@@ -127,7 +147,7 @@ Either command will create a directory called `sampel-palnet/` and begin buildin
128When 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.
148When 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.
130−To shut down your ship, use `Ctrl-d`.
150+To shut down your ship, use `Ctrl-d`.
132To start your ship up again, run `./urbit sampel-palnet/` from the directory
152To start your ship up again, run `./urbit sampel-palnet/` from the directory
133where your Urbit binary is saved. Note that in this usage,
153where 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
175The `>=` output means that a command was successful. Now you can see your ship's files in its Unix directory.
195The `>=` output means that a command was successful. Now you can see your ship's files in its Unix directory.
179## Using Landscape
197## Using Landscape
181Landscape 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:
199Landscape 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:
1831. 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.
2011. 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.
1853. Type `+code` into your ship's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
2033. Type `+code` into your ship's Dojo. Copy-paste the returned code into the field asking for it in the browser page.
1864. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
2044. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.