Get on Urbit

Urbit is two things: Urbit ID, and Urbit OS. To get on the network, you'll need both.

This guide will walk through the steps of getting an Urbit ID, downloading its key, installing the Urbit runtime, and using that to boot up your Urbit OS.

Get on Urbit faster

If you want a quicker and easier way to get on Urbit, you can skip this guide and use a hosting provider instead. Tlon offers a free Urbit ID and hosting in the cloud that only takes a few clicks to get up and running, available here.

Requirements

• Ability to use a terminal / command line. We'll go through everything you need to do step by step.

• If you want to buy an Urbit ID you will need either...

  • A credit card

  • Some ETH and familiarity with Ethereum wallets, gas fees, security best practices, etc.

• A computer or server running macOS or Linux, with at least 4GB of RAM and around 4GB of disk space. (You can usually get away with 2GB of RAM plus a swapfile and less disk space, but this might become a problem in the future as your Urbit grows.)

(If you want to run Urbit on a Windows computer you should be able to do so with Windows Subsystem for Linux (WSL), but that's outside the scope of this guide.)

If you're on mobile, open this page on a desktop and complete the following instructions on that.

1. Get an Urbit ID

Every Urbit OS server is made unique by its Urbit ID, which others can use to reach you on the network. There are five ranks of Urbit ID, but the one an ordinary user needs is a planet, which has a four-syllable name like "~sampel-palnet". Unless you know someone who can gift you one, or you want to get one from a cloud hosting provider like Tlon, you'll need to buy one.

If you don't want to buy anything at this stage, you can get on the network with a free, disposable ID called a comet. Comets can do almost everything a planet can do, but select groups on the network may refuse entry to prevent spam and abuse.

If you just want to run an Urbit locally for testing/development purposes, without networking, you can boot a "fake ship" that uses an Urbit ID you don't actually own.

To boot a comet or fake ship, skip straight to Step 3.

You can also get a planet for free with cloud hosting.

Here are the best places to buy planets:

Layer	Market	Description
Layer 1	OpenSea	The largest NFT marketplace. Accepts ETH.
Layer 2	azimuth.shop	Third-party L2 planet store. Accepts ETH.
Layer 2	Pocwet	Third-party L2 planet store. Accepts credit cards.

Originally, all Urbit IDs were ERC-721 NFTs on Ethereum. In 2021, Tlon introduced a Layer 2 solution to reduce transaction costs on Ethereum. This means there are two places where ownership of your Urbit ID could be recorded:

• Layer 1: These ordinary NFTs can traded on regular NFT marketplaces like OpenSea, and other smart contracts can interact with them. It'll cost you a bit of gas if you need to do an onchain action like a factory reset or changing your networking keys. Ownership of these IDs is recorded in Urbit's Azimuth.eth smart contract.

• Layer 2: With a Layer 2 planet you pay no transaction fee for onchain actions like factory resets and key changes. (Tlon runs the L2 system you'll use by default and they pay the very small L2 fees.) However, normal Ethereum smart contracts and NFT marketplaces cannot see or interact with L2 IDs. While there have been proposals to offer an L2 -> L1 bridge that would turn L2 IDs into ordinary NFTs on Ethereum, you should not assume this will come to pass when making a purchase decision. Ownership of your Urbit ID is not recorded in the Azimuth smart contract, but every onchain transaction associated with your ID is recorded on Ethereum.

In either case, your ownership of your planet is secured by your private key. Only you can access your Urbit ID, only you can boot up an Urbit server with your ID. Messages attributed to your ID will only ever come from your Urbit. Nobody can take your ID away from you unless they know your private key, and nobody should know your private key. Your Urbit is yours, forever.

2. Get your keyfile

Once you've got an Urbit ID, the next step is to download its private networking key (contained in a "keyfile") so you can boot it up. This process can vary depending on how you obtained your ID and where it's stored.

In a wallet

If you got an L1 planet from somewhere like OpenSea, it was likely transferred directly to your Ethereum wallet. Here are the steps to get your keyfile:

1. Go to bridge.urbit.org.

2. Conect your wallet.

3. Click on your planet, which should be listed there. (If you only have one Urbit ID in your wallet, click "Set Network Keys" on the popup and go to Step 5.)

4. Go to the "OS" section.

5. Click "Initialize" next to "Network Keys". (See the note below if it says something else.)

6. Make sure you have a little ETH to pay the transaction fee, then click on "Set Network Keys".

7. Click "Send Transaction".

8. Approve the transaction in your wallet.

9. Wait until the transaction completes and it says "Network Keys have been set" in bridge.urbit.org.

10. Click "Download Keyfile". Ignore the prompt about |rekey.

11. A file called something like sampel-palnet-1.key will have been downloaded. Don't lose it; you'll need it for the next step.

Don't see "Initialize"?

If the options next to "Networking Keys" are "Reset" and "View" rather than "Initialize", it means your ID's previous owner at one point generated keys for their planet. In that case, click on "Reset", tick the "Factory Reset" box, and continue from step 6 above.

Invite link

If you bought an L2 planet, you might have received an invite link that looks like https://bridge.urbit.org/#foshec-moplec-haddem-poddun-sampel-palnet. Here are the steps to get your keyfile:

1. Open the link and complete the steps as prompted.

2. At one point, there'll be an option to "Download Backup (Passport)". Click on that, and it'll download a file named something like like sampel-palnet-passport.zip.

3. Once you see the a message like "Congratulations, ~sampel-palnet is now yours", you can close the window and return to this page.

4. Unzip the sampel-palnet-passport.zip file. It will contain your keyfile, titled something like sampel-palnet-1.key.

5. Store your Master Ticket and Management Proxy somewhere safe. As long as you know your Master Ticket (e.g. "~sampel-ticlyt-migfun-falmel"), you can always log into bridge.urbit.org and retrieve all the other information you need.

Already have a planet?

If you already claimed this planet at some point and forgot to download the passport, you'll need to go and download your keyfile from bridge.urbit.org:

1. Go to bridge.urbit.org.

2. Click the "Master Ticket" login option.

3. Enter the planet name and Master Ticket code, and click "Login".

4. Go to the "OS" section.

5. Click on "Download Keyfile" and it'll download a file with a name like sampel-palnet-2.key.

Passport / Master Ticket

If you bought an L2 planet you might have received a "passport" or "Master Ticket". (As well as a file titled Master Ticket, there may be a file titled "Management Proxy" which you can ignore for now.) Here are the steps to get your keyfile:

1. Go to bridge.urbit.org.

2. Click the "Master Ticket" login option.

3. Enter the Urbit ID (or "Point") and the Master Ticket (e.g. "~sampel-ticlyt-migfun-falmel") from the file titled Master Ticket.

4. Click the "OS" section and click "Download Keyfile". This file should be named something like sampel-palnet-1.key.

5. Store your Master Ticket and Management Proxy somewhere safe. As long as you know your Master Ticket, you can always log into bridge.urbit.org and retrieve all the other information you need.

3. Get the Urbit runtime

To boot up a new Urbit, you'll need the Urbit runtime. There are four pre-built versions of the runtime available, one for each platform we support. Pick the one you're on and copy/paste the provided curl command into your terminal.

macOS (Apple Silicon)

Open a terminal and run:

curl -L https://urbit.org/install/macos-aarch64/latest | tar xzk -s '/.*/urbit/'

macOS (Intel)

Open a terminal and run:

curl -L https://urbit.org/install/macos-x86_64/latest | tar xzk -s '/.*/urbit/'

Linux (x86_64)

Open a terminal and run:

curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g'

Linux (aarch64)

Open a terminal and run:

curl -L https://urbit.org/install/linux-aarch64/latest | tar xzk --transform='s/.*/urbit/g'

4. Boot up your Urbit

Boot a planet

Having acquired a planet and downloaded its keyfile, you can now boot up your Urbit.

The easiest way to run an Urbit is inside a screen session. screen is installed on macOS and Linux by default; it lets you "detach" from terminal sessions, leave them running in the background, then "attach" to them again later.

To start a new screen session and name it urbit, run the following command in your terminal:

screen -S urbit

You are now inside a screen session. You can boot your Urbit with the command below, replacing sampel-palnet with your actual planet name, and /path/to/sampel-palnet-1.key with the path to the keyfile you downloaded previously. (If you're on macOS, it's probably ~/Downloads/sampel-palnet-1.key.)

./urbit -w sampel-palnet -k /path/to/sampel-palnet-1.key

(Very rarely this can result in an error message pre-boot error: %not-keyed. If you see this, check your ETH wallet in Etherscan for a "Configure Keys" transaction. If you've confirmed your planet's keys have been set, leave it for a while and try again.)

Your planet will begin to boot up, which will take a few minutes. You'll know your planet has booted when you see something like this in the terminal:

~sampel-palnet:dojo>

This is the Dojo, Urbit's command-line interface.

For the moment, shut the ship down again by typing |exit or pressing Ctrl+D. If you see a loading spinner like "<<behn>>", you won't be able to type until that goes away. Your planet might be installing a couple of apps, but since Urbit OS has no concept of RAM you can safely turn it off at any time without worrying about breaking it.

Linux default port

Linux won't let Urbit's web server bind port 80, and it will instead default to port 8080. If you want it to bind port 80, you'll need to do the following in the terminal:

# if you're on ubuntu and don't already have setcap
sudo apt-get install libcap2-bin
# replace sampel-palnet with the actual folder name
sudo setcap 'cap_net_bind_service=+ep' sampel-palnet/.run

For ease of portability the Urbit runtime has made a copy of itself in the sampel-palnet folder, so you don't need the separate urbit executable anymore. Delete it by typing rm urbit.

At this point you can also delete your keyfile because it can never be used again.

Spin up your planet again by running sampel-palnet/.run, and you'll be back at the Dojo.

Next, you'll want to get the web login code so you can login to your Urbit's web interface in a browser.

To do so, type +code in the Dojo and press Return. It'll give you a code that looks like lidlut-tabwed-pillex-ridrup. Highlight that and copy it.

Save your code

If you want, you can save your +code in a password manager or write it down somewhere safe. Your +code isn't your private key, just a web login password. If you think your +code has been compromised, you can just reset it in the Dojo to log out of all browser sessions in your Urbit.

Detach from this screen session by hitting Ctrl+A, then hitting D. It should say something like [detached from 1819892.urbit]. You can now close or quit the terminal entirely; your Urbit is still running in the screen session.

If you need to get back to the Dojo again in the future, just open a terminal and run screen -r urbit to reattach to the urbit session.

Mine a comet

Comets are free, disposable Urbit IDs. Comets are trivial to create, so we use them as anonymous IDs, but to boot an Urbit server with a comet you'll have to "mine" one.

The easiest way to run an Urbit is inside a screen session. screen is installed on macOS and Linux by default; it lets you "detach" from terminal sessions, leave them running in the background, then "attach" to them again later.

To start a new screen session and name it urbit, run the following command in your terminal:

screen -S urbit

Now that you're in a screen session, you can mine a new comet with the command below. mycomet is just the name of the folder, so you can change it to whatever you like.

./urbit -c mycomet

It might take a few minutes to boot up and mine a comet. You'll know your comet has booted when you see something like this in the terminal:

~sampel_litzod:dojo>

This is the Dojo, Urbit's command-line interface.

For the moment, shut the ship down again by typing |exit or pressing Ctrl+D. If you see a loading spinner like "<<behn>>", you won't be able to type until that goes away.

Linux default port

Linux won't let Urbit's web server bind port 80, and it will instead default to port 8080. If you want it to bind port 80, you'll need to do the following in the terminal:

# if you're on ubuntu and don't already have setcap
sudo apt-get install libcap2-bin
# replace mycomet with the actual folder name
sudo setcap 'cap_net_bind_service=+ep' mycomet/.run

For ease of portability the Urbit runtime has made a copy of itself in the mycomet folder, so you don't need the separate urbit executable anymore. Delete it by typing rm urbit.

Spin up your comet again by running mycomet/.run, and you'll be back at the Dojo.

Comets don't receive software updates by default. If you intend on running this comet for a while and you want to receive updates, run |ota in the Dojo.

Next, you'll want to get the web login code so you can login to your Urbit's web interface in a browser.

To do so, type +code in the Dojo and press Return. It'll give you a code that looks like lidlut-tabwed-pillex-ridrup. Highlight that and copy it.

Save your code

If you want, you can save your +code in a password manager or write it down somewhere safe. Your +code isn't your private key, just a web login password. If you think your +code has been compromised, you can just reset it in the Dojo to log out of all browser sessions in your Urbit.

Detach from this screen session by hitting Ctrl+A, then hitting D. It should say something like [detached from 1819892.urbit]. You can now close or quit the terminal entirely; your Urbit is still running in the screen session.

If you need to get back to the Dojo again in the future, just open a terminal and run screen -r urbit to reattach to the urbit session.

Boot a fake ship

Fake ships are for development purposes only and cannot connect to the live network.

Run the urbit executable you previously downloaded with the -F flag to boot a new fake ship. You can specify any identity you want. Most people use the galaxy ~zod.

./urbit -F zod

This will take a few minutes. Once it's done, you'll have a responsive prompt that looks like this:

~zod:dojo> 

You can shut the fake ship down by typing |exit or pressing Ctrl+D.

For ease of portability the Urbit runtime has made a copy of itself in the zod folder, so you don't need the separate urbit executable anymore. Delete it by typing rm urbit.

Spin up your fake ship again by running zod/.run, and you'll be back at the Dojo.

Next, you may want to get the web login code so you can login to your Urbit's web interface in a browser. To do so, type +code in the Dojo and press Return. It'll give you a code that looks like lidlut-tabwed-pillex-ridrup. Highlight that and copy it.

Fake ships are for developers. If you want to learn more about programming, app development, or core development on Urbit, look at our courses section to get started.

5. Login to Landscape

With your Urbit now running and your web login code copied, you can open a browser and go to http://localhost. (If that doesn't work, try http://localhost:8080.) You should see with your Urbit's login screen. Paste in the code you got from running +code in the Dojo (it looks like lidlut-tabwed-pillex-ridrup) and click "Continue". You'll now be in your Landscape homescreen.

To join your first group, you can open the Tlon app by clicking on its tile, then click the + in the sidebar and click "Join a group". Paste in ~halbex-palheb/uf-public, the Urbit Foundation's official public group, and click "Go", then click "Join group".

Have a look at the Urbit Foundation group for a list of more groups on the network to join.

If you'd like to see what apps are available other than Tlon, click on the "Get Urbit Apps" button at the top of the Landscape homescreen. There are a few suggestions listed there. If you know an app's publisher (e.g. ~bitdeg) or "shortcode" (e.g. ~bitdeg/hits), you can type that in the searchbar at the top of the "Get Urbit Apps" menu.