git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/getting-started/planet.md
216 lines 11 kB history raw
1+++
2title = "Setting up your urbit"
3weight = 2
4description = "Getting started with a permanent Urbit identity."
5+++
7A planet is a permanent Urbit identity. Like all Urbit identities, they can
8never be taken away from you. Unlike comets which are free, planets are designed
9for use well into the future. If you're not yet familiar with the Urbit network
10and are looking to try it out with a free Comet, are looking to purchase a
11planet, or are looking for an easy hosting solution, see the [Getting Started
12guide](/getting-started/) instead. This guide is for those who have already
13obtained a planet and want to get it running for the first time.
15## Step 1: Keyfile {#keyfile}
17The Urbit runtime needs a planet's keyfile in order to boot it up for the first
18time. The keyfile contains the private cryptographic keys necessary for a planet
19to sign messages it sends and decrypt messages it receives. These keys are
20separate from either your Master Ticket (if applicable) or the Ethereum keys
21used to manage your Urbit ID. The method to obtain your planet's keyfile differs
22slightly, depending on whether you're on a Master Ticket or use an alternative
23custody method like a Metamask wallet, hardware wallet, etc.
25### Master Ticket
27A Master Ticket is like a paper wallet for your planet. From the planet name and
28Master Ticket password, [Bridge](https://bridge.urbit.org) can derive everything
29necessary to manage your Urbit ID, such as Ethereum addresses, networking keys,
30and so on.
32If you received an email invite to Urbit or were otherwise given an invite URL
33and claimed your planet that way, you'll likely be on a Master Ticket. To get
34the keyfile, you can look in the `.zip` file you downloaded when claiming your
35planet - it'll be named `sampel-palnet-1.key` (except with your planet rather
36than `sampel-palnet`).
38If 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
40and Master Ticket password. Once in, click on `OS` and then `Download Arvo Keyfile`.
42### Other methods
44If 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
47transferred the planet to an Ethereum address you own, you will probably not be
48on a Master Ticket. This is perfectly fine and you don't need to transfer your
49planet to a Master Ticket if you don't want to. The one small difference,
50though, is that Bridge will not have automatically derived your keyfile.
51Instead, you'll need to login to [Bridge](https://bridge.urbit.org) and perform
52a transaction to set your Networking keys.
54When you visit [Bridge](https://bridge.urbit.org), you'll need to select the
55login option that says `Metamask, Mnemonic, Hardware Wallet...`, and it will
56have 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
76secrets across the network or store any secrets on a remote server. If you'd
77prefer though, it's also possible to run the Bridge software locally (though
78it's a little more more complicated), see the [Readme in the Bridge Github
79repo](https://github.com/urbit/bridge) for details.</small>
81If you've been transferred a planet and not yet accepted it, you'll need to do
82that first (you can skip this bit if you've already done it). Having logged in
83with one of the methods described above, you'll see see an `Incoming Transfer`
84request. Click `Accept`, then click `Generate & Sign Transaction` (This will
85require some ETH for transaction fees). Once the transaction's complete, click
86on `return`.
88Now that you're logged in to Bridge and have your planet, you can set the
89networking 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
91can leave `Breach Continuity` unchecked. Send the transaction (this will require
92some ETH for transaction fees). Once complete, you can click `Download Arvo Keyfile` and save the `.key` file on your computer.
94## Step 2: Install
96Urbit must run on an existing computer somewhere. Some users run their planet on
97their personal computer, but we recommend eventually using a cloud service
98(Digital Ocean, Linode, etc) because it allows your planet to be accessed from
99anywhere on multiple devices. Hosting your planet in the cloud also allows it to
100always be online and ready for automatic updates. You are welcome to run from
101your personal computer and switch to the cloud later...all without losing any
102data!
104### Port
106Port is an Urbit GUI application available for MacOS, Linux and Windows. This
107option is much easier but runs locally rather than in the cloud. Note that if
108you have your planet in the cloud, Port can also be used as a client to connect
109to your planet's web interface. [You can download Port
110here](/getting-started#port).
112### Command line
114Running Urbit from the command line is suitable for either a cloud installation
115or a local installation. If you're comfortable with the command line and would
116like greater control over the Urbit virtual machine, this is the right option.
117The Urbit runtime is available for Linux, MacOS and Windows.
118Additionally, there are guides for [hosting your planet on
119DigitalOcean](/using/running/hosting) and [hosting your planet on Linode
120(external
121link)](https://jeremytunnell.com/2021/01/09/how-to-install-urbit-on-a-linode-vps),
122though most other cloud providers should be fine as well. [See here for download
123and installation instructions](/getting-started/cli).
125## Step 3: Boot
127### Port
129If 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.
131**Important:** once a key has been used to boot a planet onto the network, it
132cannot be used to boot that planet again later - doing so will cause
133communication problems with other planets. For this reason you should **delete
134the keyfile from your machine once your planet has booted successfully**. If you
135do use the same key twice, you'll need to reset your planet to restore its
136functionality.
138### Command line
140For other ships on the network to communicate with your ship, the computer it's
141running on needs to be able to receive inbound UDP traffic. Therefore, it's
142important when running your ship locally to use the `-p ames_port` flag (replace
143`ames_port` with a public port number from 49152 to 65535) to specify on which
144port you'll receive UDP traffic, and to forward inbound UDP traffic arriving at
145your router on that port to your computer.
147Navigate to your `urbit` directory. Open your keyfile (it is just a text file)
148and copy the key inside to the clipboard. Paste it into the following command,
149except with `ames_port` replaced with a public port number, and `sampel-palnet`
150replaced by the name of your planet. **Do not include the tilde in your planet
151name.**
153```sh
154./urbit -p ames_port -w sampel-palnet -G rAnDoMkEy
155```
157Or you can copy the keyfile into the current directory and run:
159```sh
160./urbit -p ames_port -w sampel-palnet -k ./my-planet.key
161```
163Either command will create a directory called `sampel-palnet/` and begin booting
164your planet. It may take a few minutes.
166When your planet is finished booting, you will see `~sampel-palnet:dojo>` (Dojo:
167the Urbit command line).
169To log into [Landscape](/docs/glossary/landscape), check out the directions
170[here](/getting-started/#using-landscape).
172To shut down your planet, use `Ctrl-D`.
174To start your planet up again, run the following from your `urbit` directory,
175with `ames_port` replaced with the public port number you used when first
176booting your ship.
178```sh
179./urbit -p ames_port sampel-palnet
180```
182Note that `sampel-palnet/` is the path of a folder, which we just created in
183your `urbit` directory. This folder is called your planet's **pier**, and it
184holds all of your data.
186Never boot multiple instances of your planet at the same time. You can prevent
187this from happening on accident by only ever keeping a single copy of your pier.
189**Important:** once a key has been used to boot a planet onto the network, it
190cannot be used to boot that planet again later - doing so will cause
191communication problems with other planets. For this reason you should **delete
192the keyfile from your machine once your planet has booted successfully**. If you
193do use the same key twice, you'll need to reset your planet to restore its
194functionality.
196Delete the keyfile with the command below:
198```sh
199rm ./my-planet.key
200```
202## Next Steps
204Once 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.
206If you haven't already done so, we recommend spending a few minutes reading
207[Understanding Urbit](/understanding-urbit) to get acquainted with the project.
208Then once you've been become acquainted with your ship and explored the network
209for awhile, consider checking out the [User's Manual](/using) which provides
210guidance and reference material for operating your ship, as well as explanations
211for Urbit concepts everyone should eventually learn.
213If you're interested in developing on Urbit, check out:
215- [Learn to Develop on Urbit](/docs/development/develop): Learn how to
216 contribute to or develop on Urbit.