@@ -4,49 +4,138 @@ weight = 1
4description = "Getting started with a permanent Urbit identity."
4description = "Getting started with a permanent Urbit identity."
7−A planet is a permanent Urbit identity. Like all Urbit identities, they can never be taken away from you. Unlike comets which are free, planets are designed for use well into the future. If you're not yet familiar with the Urbit network, please follow the [Getting Started guide](/getting-started/), which will explain the basics and walk you through using a free identity. This guide explains the next steps.
7+A planet is a permanent Urbit identity. Like all Urbit identities, they can
8−
8+never be taken away from you. Unlike comets which are free, planets are designed
9−### Purchase a planet {#purchase}
9+for use well into the future. If you're not yet familiar with the Urbit network
10−
10+and are looking to try it out with a free Comet, are looking to purchase a
11−There are a few ways to get your own planet:
11+planet, or are looking for an easy hosting solution, see the [Getting Started
12−
12+guide](/getting-started/) instead. This guide is for those who have already
13−- Getting an invitation from a friend (or stranger).
13+obtained a planet and want to get it running for the first time.
14−- Purchasing a planet, including hosting, from a [hosting provider](#hosting-providers).
14+
15−- Manually setting up and hosting a planet purchased from a third party such as [urbit.live](https://urbit.live), [OpenSea](https://opensea.io), [planet.market](https://planet.market/), [urbit.me](https://urbit.me), [urth systems](https://urth.systems/), or [Urbit Marketplace](https://urbitmarketplace.com/).
15+## Step 1: Keyfile {#keyfile}
17−Note that when you buy a planet, you should ensure with the provider that your parent star is operating. If you need to escape a non-operational star, see [Escaping A Sponsor](/using/id/using-bridge#escaping-your-sponsor).
17+The Urbit runtime needs a planet's keyfile in order to boot it up for the first
18−
18+time. The keyfile contains the private cryptographic keys necessary for a planet
19−### Hosting Providers {#hosting-providers}
19+to sign messages it sends and decrypt messages it receives. These keys are
20−
20+separate from either your Master Ticket (if applicable) or the Ethereum keys
21−Hosting providers will often sell you a planet and run it for you. This option is very simple but will probably cost a regular fee.
21+used to manage your Urbit ID. The method to obtain your planet's keyfile differs
22−
22+slightly, depending on whether you're on a Master Ticket or use an alternative
23−Urbit is designed to be portable. This means that if you sign up for hosting now but later want to leave your hosting provider and run your Urbit yourself, you should be able to work with them to obtain all of your data and boot your planet back up without losing anything.
23+custody method like a Metamask wallet, hardware wallet, etc.
25−Using hosting does mean that you're trusting your provider with your data, but so long as you have your planet, you'll always own your identity.
25+### Master Ticket
27−Current hosting providers are:
27+A Master Ticket is like a paper wallet for your planet. From the planet name and
28−
28+Master Ticket password, [Bridge](https://bridge.urbit.org) can derive everything
29−- [escape pod store](https://www.escapepod.store/)
29+necessary to manage your Urbit ID, such as Ethereum addresses, networking keys,
30−- [Third Earth](https://third.earth/)
30+and so on.
31−- [Tlon Corporation](https://tlon.io)
31+
32−- [UrbitHost](https://urbithost.com)
32+If you received an email invite to Urbit or were otherwise given an invite URL
33−
33+and claimed your planet that way, you'll likely be on a Master Ticket. To get
34−### Choose to run your planet on your computer or on a cloud service
34+the keyfile, you can look in the `.zip` file you downloaded when claiming your
35−
35+planet - it'll be named `sampel-palnet-1.key` (except with your planet rather
36−Urbit must run on an existing computer somewhere. Most users run their planet on their personal computer, but we recommend eventually using a cloud service (Digital Ocean, Linode, etc) because it allows your planet to be accessed from anywhere on multiple devices. Hosting your planet in the cloud also allows it to always be online and ready for automatic updates. You are welcome to run from your personal computer and switch to the cloud later...all without losing any data!
36+than `sampel-palnet`).
38+If you have misplaced that `.key` file, you can also download it from
39+[Bridge](https://bridge.urbit.org). First, login to Bridge with your planet name
40+and Master Ticket password. Once in, click on `OS` and then `Download Arvo Keyfile`.
44+If you bought your planet from a third party such as
45+[OpenSea](https://opensea.io), [urbit.live](#https://urbit.live), or another
46+[third party](/getting-started#get-a-planet), or otherwise if someone
47+transferred the planet to an Ethereum address you own, you will probably not be
48+on a Master Ticket. This is perfectly fine and you don't need to transfer your
49+planet to a Master Ticket if you don't want to. The one small difference,
50+though, is that Bridge will not have automatically derived your keyfile.
51+Instead, you'll need to login to [Bridge](https://bridge.urbit.org) and perform
52+a transaction to set your Networking keys.
54+When you visit [Bridge](https://bridge.urbit.org), you'll need to select the
55+login option that says `Metamask, Mnemonic, Hardware Wallet...`, and it will
56+have a list of options:
58+- `Metamask` - If your planet is owned by your Metamask wallet, select this. It
59+ may prompt you to login to Metamask, then it will ask you to sign the `Bridge Authentication Token`. Once signed, you'll be logged into Bridge.
61+- `Ledger` and `Trezor` - If your planet is owned by one of these hardware
62+ wallets, select the appropriate one and follow its connection process.
64+- `WalletConnect` - If your planet is owned by a wallet which supports the
65+ WalletConnect protocol, select this and either scan the QR code or select one
66+ of the desktop options.
68+- `Mnemonic`, `Ethereum Private Key` and `Ethereum Keystore` - If your planet is
69+ owned by another Ethereum wallet which does not support WalletConnect, you can
70+ still login with one of these. `Mnemonic` lets you paste in the BIP39 mnemonic
71+ seed phrase (a series of random words) for your wallet. `Ethereum Private Key`, as the name suggests, lets you paste in the private key of the Ethereum
72+ address which owns your planet. `Ethereum Keystore` lets you upload an
73+ Ethereum keystore file and specify its password for decryption.
75+<small>Note: Bridge runs purely in your local browser, it does not transfer any
76+secrets across the network or store any secrets on a remote server. If you'd
77+prefer though, it's also possible to run the Bridge software locally (though
78+it's a little more more complicated), see the [Readme in the Bridge Github
79+repo](https://github.com/urbit/bridge) for details.</small>
81+If you've been transferred a planet and not yet accepted it, you'll need to do
82+that first (you can skip this bit if you've already done it). Having logged in
83+with one of the methods described above, you'll see see an `Incoming Transfer`
84+request. Click `Accept`, then click `Generate & Sign Transaction` (This will
85+require some ETH for transaction fees). Once the transaction's complete, click
88+Now that you're logged in to Bridge and have your planet, you can set the
89+networking keys. From the main screen for your planet, hit `OS` and then
90+`Initialize Networking Keys`. If the planet has never been spawned before, you
91+can leave `Breach Continuity` unchecked. Send the transaction (this will require
92+some ETH for transaction fees). Once complete, you can click `Download Arvo Keyfile` and save the `.key` file on your computer.
96+Urbit must run on an existing computer somewhere. Some users run their planet on
97+their personal computer, but we recommend eventually using a cloud service
98+(Digital Ocean, Linode, etc) because it allows your planet to be accessed from
99+anywhere on multiple devices. Hosting your planet in the cloud also allows it to
100+always be online and ready for automatic updates. You are welcome to run from
101+your personal computer and switch to the cloud later...all without losing any
106+Port is an Urbit GUI application available for MacOS, Linux and Windows. This
107+option is much easier but runs locally rather than in the cloud. Note that if
108+you have your planet in the cloud, Port can also be used as a client to connect
109+to your planet's web interface. [You can download Port
110+here](/getting-started#port).
114+Running Urbit from the command line is suitable for either a cloud installation
115+or a local installation. If you're comfortable with the command line and would
116+like greater control over the Urbit virtual machine, this is the right option.
117+The Urbit runtime is available for Linux, MacOS, and can also be run on Windows
118+by using WSL2. Additionally, there are guides for [hosting your planet on
38−There is a guide for [hosting your planet on DigitalOcean](/using/running/hosting) and [hosting your planet on Linode](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps), but any cloud hosting service should work.
119+DigitalOcean](/using/running/hosting) and [hosting your planet on Linode
40−### Get your keyfile {#keyfile}
121+link)](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps),
41−
122+though most other cloud providers should be fine as well. [See here for download
42−If you received an email invite to Urbit, the master ticket should be a .pdf file in the passport folder inside the archive that you downloaded. **If you bought your planet or someone sent you one you probably do not have a master ticket, and you probably don't need one. Do not issue a new master ticket unless you are sure you need to.**
123+and installation instructions](/getting-started/cli).
44−1. Connect to [Bridge](https://bridge.urbit.org). (Bridge is like an Urbit wallet)
125+## Step 3: Boot
45−2. Enter the name of your planet and the associated master ticket if you have one. Click the "Metamask, Mnemonic, Hardware Wallet..." button if you don't have a master ticket.
126+
46−3. Once you're logged in, click the "OS" option.
127+### Port
47−4. Click the "Download Arvo Keyfile" button. If this is grayed out, click on "Reset Networking Keys", then click on "Reset Networking Keys" on the following page, validate the transaction using your wallet, and then click "Send Trasaction". Once the transaction is complete, the "Download Arvo Keyfile" button should be available for you to press. You should receive a `.key` file that contains the secret needed to boot your planet. Hold onto this file.
128+
48−
129+If you've decided to use Port, booting is very simple. Just start up Port and select `Boot a fresh ID`. Then, give your ship a name in the `Name` field - this is just for convenience, a label used locally by Port to identify your planet. In the `Shipname` field, just enter your planet name like `~sampel-palnet`. Lastly, for the `Key File`, you can browse to the keyfile you downloaded in [Step 2](#keyfile), select it, and hit `Continue`. It'll take a few minutes to boot up your ship, and then you should be good to go.
49−### Run the boot command {#the-dojo}
130+
131+**Important:** once a key has been used to boot a planet onto the network, it
132+cannot be used to boot that planet again later - doing so will cause
133+communication problems with other planets. For this reason you should **delete
134+the keyfile from your machine once your planet has booted successfully**. If you
135+do use the same key twice, you'll need to reset your planet to restore its
51For other ships on the network to communicate with your ship, the computer it's
140For other ships on the network to communicate with your ship, the computer it's
52running on needs to be able to receive inbound UDP traffic. Therefore, it's
141running on needs to be able to receive inbound UDP traffic. Therefore, it's
@@ -56,9 +145,10 @@ port you'll receive UDP traffic, and to forward inbound UDP traffic arriving at
56your router on that port to your computer.
145your router on that port to your computer.
58Navigate to your `urbit` directory. Open your keyfile (it is just a text file)
147Navigate to your `urbit` directory. Open your keyfile (it is just a text file)
59−and copy the key inside. Paste it into the following command, except with
148+and copy the key inside to the clipboard. Paste it into the following command,
60−`ames_port` replaced with a public port number, and `sampel-palnet` replaced by
149+except with `ames_port` replaced with a public port number, and `sampel-palnet`
61−the name of your planet. **Do not include the tilde in your planet name.**
150+replaced by the name of your planet. **Do not include the tilde in your planet
64./urbit -p ames_port -w sampel-palnet -G rAnDoMkEy
154./urbit -p ames_port -w sampel-palnet -G rAnDoMkEy
@@ -70,25 +160,38 @@ Or you can copy the keyfile into the current directory and run:
70./urbit -p ames_port -w sampel-palnet -k ./my-planet.key
160./urbit -p ames_port -w sampel-palnet -k ./my-planet.key
73−Either command will create a directory called `sampel-palnet/` and begin booting your planet. It may take a few minutes.
163+Either command will create a directory called `sampel-palnet/` and begin booting
164+your planet. It may take a few minutes.
75−When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo: the Urbit command line).
166+When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo:
167+the Urbit command line).
77−To log into [Landscape](/docs/glossary/landscape), check out the directions [here](/getting-started/#using-landscape).
169+To log into [Landscape](/docs/glossary/landscape), check out the directions
170+[here](/getting-started/#using-landscape).
79To shut down your planet, use `Ctrl-D`.
172To shut down your planet, use `Ctrl-D`.
81−To start your planet up again, run the following from your `urbit` directory, with `ames_port` replaced with the public port number you used when first booting your ship.
174+To start your planet up again, run the following from your `urbit` directory,
175+with `ames_port` replaced with the public port number you used when first
84./urbit -p ames_port sampel-palnet
179./urbit -p ames_port sampel-palnet
87−Note that `sampel-palnet/` is the path of a folder, which we just created in your `urbit` directory. This folder is called your planet's **pier**, and it holds all of your data.
182+Note that `sampel-palnet/` is the path of a folder, which we just created in
183+your `urbit` directory. This folder is called your planet's **pier**, and it
184+holds all of your data.
186+Never boot multiple instances of your planet at the same time. You can prevent
89−Never boot multiple instances of your planet at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
187+this from happening on accident by only ever keeping a single copy of your pier.
91−**Important:** once a key has been used to boot a planet onto the network, it cannot be used to boot that planet again later - doing so will cause communication problems with other planets. For this reason you should **delete the keyfile from your machine once your planet has booted successfully**. If you do use the same key twice, you'll need to reset your planet to restore its functionality.
189+**Important:** once a key has been used to boot a planet onto the network, it
190+cannot be used to boot that planet again later - doing so will cause
191+communication problems with other planets. For this reason you should **delete
192+the keyfile from your machine once your planet has booted successfully**. If you
193+do use the same key twice, you'll need to reset your planet to restore its
93Delete the keyfile with the command below:
196Delete the keyfile with the command below:
@@ -96,37 +199,18 @@ Delete the keyfile with the command below:
96rm ./my-planet.key
199rm ./my-planet.key
99−## Setup {#setup}
202+## Next Steps
101−The first thing you generally want to do with a new planet is to **mount** it. A planet being mounted means that it can be seen by Linux, allowing files to be shared between it and your planet. To mount your planet, type `|mount %` at the Dojo prompt.
108−The `>=` output means that a command was successful. Now you can see your planet's files in its directory.
110−To understand what happened with this command, read more about Urbit’s filesystem (called “clay”) [here](/docs/arvo/clay/clay).
112−## Updating {#updating}
114−By default, planets have a sponsor — a star that provides updates and routing services. To see who you receive updates from, enter `|ota` in the dojo. You will see something like this:
117−~sampel-palnet:dojo> |ota
118−OTAs enabled from %kids on ~dopzod
119−use |ota %disable or |ota ~sponsor %kids to reset it
124−If for some reason your sponsor (in this case, `~dopzod`) is not responding, read instructions on [escaping your sponsor](/using/id/using-bridge#escaping-your-sponsor).
204+Once you've got your ship up and running, you might like to join the official Urbit Community group and say hello. Just click on the `Groups` app and it will open Urbit's communications suite. In Groups, hit `Join Group` and enter `~bitbet-bolbel/urbit-community`. Once joined, a new tile for the group will appear on the Groups home screen. Open that, click on the `General` channel in the sidebar, and hit `Join Channel`. It'll take a couple of minutes to download the chat history, then you'll be able to post a message.
126−## Next Steps
206+If you haven't already done so, we recommend spending a few minutes reading
207+[Understanding Urbit](/understanding-urbit) to get acquainted with the project.
208+Then once you've been become acquainted with your ship and explored the network
209+for awhile, consider checking out the [User's Manual](/using) which provides
210+guidance and reference material for operating your ship, as well as explanations
211+for Urbit concepts everyone should eventually learn.
128−Now that you’re up and running, take some time to deepen your understanding by checking out some of our other guides:
213+If you're interested in developing on Urbit, check out:
130−- [Host your Ship in the Cloud](/using/running/hosting): Follow this guide to set your ship up to run as a cloud server, accessible from anywhere.
131−- [Read the Operations Manual](/using/os/getting-started): Become an expert pilot by learning to use your ship.
132−- [Learn to Develop on Urbit](/docs/development/develop): Learn how to contribute to or develop on Urbit.
215+- [Learn to Develop on Urbit](/docs/development/develop): Learn how to
216+ contribute to or develop on Urbit.