4 title/'Getting Started'
10This guide is broken into five parts:
12+ [Acquiring an Urbit Identity](#acquire)
13+ [Using Bridge](#bridge)
14+ [Installing Arvo](#arvo)
15+ [Booting Your Ship](#boot)
16+ [Basic Operations](#operation)
18_If you just want to install the Urbit OS, Arvo, and don't need to be on the
19Urbit network, you can skip to [Installing Arvo](#arvo)._
23 ;div(id "acquire"): Acquiring an Urbit Identity
27Urbit's identity layer, called Azimuth, is a suite of contracts on the Ethereum
28blockchain. An Azimuth address, called a *point*, functions as an identity and
29a network address for Arvo, the Urbit OS. An instance of Arvo is called a
30*ship*. A ship can't use the Arvo network until it's combined with a point.
32Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
35Points are generally not freely available, so you will need to either
36purchase one or get one from a friend. This guide assumes you have found a way
39If you went through the address registration process and used [Wallet Generator](https://github.com/urbit/urbit-wallet-generator),
40then you should have have received a .zip file that contains an Ethereum address
41and cryptographic secrets in the form of a PDF.
43Your ownership PDF contains two secrets that must be kept safe.
45- *Master Ticket*: This is a master key that allows you to manage every aspect of
48- *Ownership Seed BIP39 Mnemonic*: The master ticket encoded as a BIP39 mnemonic
49 for compatibility with most Ethereum wallet software, including our own *Bridge*
54 ;div(id "bridge"): Using Bridge
58Bridge is client that we built for accessing and managing your Urbit identities.
59Like Wallet Generator, Bridge is a web application that can also be run in offline mode.
60It can be run in Firefox on all platforms, and also in Chrome if you're using
63Importantly, Bridge also allows you to generate a keyfile that
64you will need to boot your ship on the Arvo network for the first time. Once a ship
65with a keyfile, you can restart it later without the keyfile.
67*Note* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
68anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
69sure your Ethereum address has some pocket ETH.
71Download bridge [here](https://github.com/urbit/bridge/releases) and follow
72the instructions below.
78#### Step 2: Select a Network
80On the dropdown menu, make sure that `Main Network` is selected. Then click
83#### Step 3: Open a Wallet
85On this dropdown menu, choose how you'd like to access your Ethereum wallet.
86If you aren't using a hardware wallet (we support Ledger and Trezor), you'll
87want to use your Ethereum wallet's BIP39 Mnemonic.
89If you used Wallet Generator to generate an HD wallet, you have a few choices:
90you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
91permissions to update your point. The mnemonic associated with your management
92seed is also useful to perform everyday operations (such as boot your ship!).
94Select the appropriate option and click `Continue ->`.
96#### Step 4: (optional) Accept Your Transfer
98If you were sent a point by a friend, then you should see a graphic under
99`Incoming Transfers`. Click the `Details ->` link under that graphic.
101Now you'll be on the management page of your point. The transfer isn't completed
102yet, so click `Accept incoming transfer`. Then check both boxes and and click
103their associated `Sign Transaction` and `Send Transaction` buttons.
105If you already own a point, then click on the `Details ->` under your sigil in the
106`Your Points` section.
108#### Step 5: (optional) Set Your Networking Keys
110If you just accepted a point, you'll be returned to your point screen. Notice that
111that links and buttons are now clickable. You now own this point!
113Click the link that says `Generate Urbit networking keys`. Bridge will let you either
114download a keyfile derived from your networking keys are you can paste in your own
115network seed and derive a new keyfile. See our
116[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/proposals/8.md)
119#### Step 6: Generate Your Keyfile
121From the detail page associated with your point, click the `Generate Urbit Keyfile`
122button and you'll be taken to a page with a field titled `Network key`. If you went
123through the address registration process, this should be filled in already.
124Click `Generate ->`, which will download a keyfile onto your machine.
126With that keyfile in hand, you can now exit Bridge.
130 ;div(id "arvo"): Installing Arvo
134Now you're ready to run Arvo. You're almost there!
136But first, some terminology:
137- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
138- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
140Arvo runs nicely on a Unix-like operating system -- Ubuntu,
141Fedora, macOS, and FreeBSD. If you're using Windows, you'll need
142to get one of the aforementioned systems. Don't worry: most of them are free.
144We have different installation instructions for different platforms. To install
145and run Arvo, run the commands that are listed for your operating system.
147On any platform, you can check your Arvo installation by running the `urbit`
148command. Installation was successful if you get a block of output that begins
152Urbit: a personal server operating function
157We recommend using the Homebrew package manager to run Arvo on MacOS.
163brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
164git clone https://github.com/urbit/urbit
168sudo ninja -C ./build/ meson-install
178sudo apt-get install autoconf automake cmake exuberant-ctags g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev libtool make openssl pkg-config python python3 python3-pip ragel re2c zlib1g-dev
179sudo -H pip3 install --upgrade pip
180sudo -H pip3 install meson==0.29
183# 'apt-get install ninja-build' gives us 0.1.3
184# 'apt-get install ninja-build' gives us 1.3.4
186git clone git://github.com/ninja-build/ninja.git
189 ./configure.py --bootstrap
190 sudo cp ./ninja /usr/local/bin
194git clone https://github.com/urbit/urbit
198sudo ninja -C ./build/ install
208sudo yum install autoconf automake cmake ctags gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel libtool ncurses-devel ninja-build openssl openssl-devel pkgconfig python2 python3 ragel re2c wget
210# meson requires python 3.5; RHEL supplies wrong version
212 sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
213 sudo tar xzf Python-3.5.5.tgz
215 sudo ./configure --enable--optimizations
219 sudo ln -s python3.5 python3
223curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
224sudo /usr/local/bin/python3 get-pip.py
225# downgrade meson to avoid dependencies that redhat can't meet
226sudo -H /usr/local/bin/pip3 install meson==0.29
229git clone git://github.com/ninja-build/ninja.git && cd ninja
231./configure.py --boostrap
232sudo cp ./ninja /usr/local/bin
234git clone https://github.com/urbit/urbit
238sudo /usr/local/bin/ninja -C ./build/ install
248sudo pacman -S autoconf automake cmake curl gcc git gmp libsigsegv libtool ncurses ninja openssl python ragel re2c
249curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
250sudo python3 get-pip.py
251git clone https://github.com/urbit/urbit
255sudo ninja -C ./build/ meson-install
259If you just want to use a fake ship for development purposes, you can now use
260the command of the scheme below to boot a fake `~zod`.
263urbit -F zod -A /path/to/arvo -s -c zod
266If you want to get on the Arvo network with your point, then continue to the
272 ;div(id "boot"): Booting Your Ship
277Now the rubber meets the road. You'll be booting your ship with the keyfile
278that you downloaded from Bridge.
280#### Step 1: Find Your Point's Name
282This will look something like `~lodleb-ritrul`. You can see the name of your
283point(s) when you log into your wallet using the Bridge client.
285;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
287#### Step 2: Find the path to your keyfile
289Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
291#### Step 3: Run the boot command
293Type `cd` in your terminal to return to your home directory. If you want to
294store your ship somewhere besides your home directory, change the terminal's
295working directory to the desired directory.
297Run the command below, except with `~sample-planet` replaced by the name of your
298Urbit identity, and `path/to/my-planet.key` replaced with the path to your
302urbit -w ~sample-planet -k path/to/my-planet.key
305if you'd prefer to copy your key in you can run
308urbit -w ~sample-planet -G rAnDoMkEy
312This will create a directory called `sample-planet/` and begin building your
313ship. It may take a few minutes.
315When your ship is finished booting, you will see the `~sample-planet:dojo>`
316prompt. At that point, you should permanently erase your keyfile from your
321 ;div(id "operation"): Basic Operations
325Welcome to your urbit! There's a few things you should do to become oriented.
329Let's try out the Dojo, the Arvo command line and Hoon REPL:
332~sample-planet:dojo> (add 2 2)
346Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
350~sample-planet:dojo> |mount %
359which indicates that the command was processed.
361`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
362Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files are automatically synced into your ship.
367Use `ctrl-x` to toggle between the Dojo and the Talk prompts.
369While on the Talk prompt, let's join the main Urbit support chat channel, `/urbit-help`:
372~sample-planet:talk[] ;join /urbit-help
375Talk is stateful, so your ship will download a backlog. `/urbit-help` is the
376place to ask questions about getting up and running.
378#### Shutting Down and Restarting
380You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
382To restart your ship, simply pass the name of your pier:
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list