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 a 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
65you will need to boot your ship on the Arvo network for the first time. Once you boot a ship
66with a keyfile, you can restart it later without the keyfile.
68*Note* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
69anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
70sure your Ethereum address has some pocket ETH.
72Download Bridge [here](https://github.com/urbit/bridge/releases) and follow
73the instructions below.
77Click `Unlock a Wallet`.
79#### Step 2: Select a Network
81On the dropdown menu, make sure that `Main Network` is selected. Then click
84#### Step 3: Unlock a Wallet
86On this dropdown menu, choose how you'd like to access your Ethereum wallet.
87If you aren't using a hardware wallet (we support Ledger and Trezor), you'll
88want to use your Ethereum wallet's BIP39 Mnemonic.
90If you used Wallet Generator to generate an HD wallet, you have a few choices:
91you can choose `Urbit Master Ticket,` which is high-value, but allows you unfettered
92permissions to update your point. The mnemonic associated with your management
93seed is also useful to perform everyday operations (such as boot your ship!).
95Select the appropriate option and click `Continue ->`.
97If you already have a point -- for example, if you are trying to boot a ship
98from a pre-Ethereum-era network -- you should see a list of points associated with your
99keys. If you are trying to boot a planet for the first time, click on the
100`Details` link for that point. At the bottom on the Details page, there is
101a section called `Urbit Networking`. If the fields in this section are filled out, proceed to step 6.
103If you do not yet have a point and are getting one sent to you, proceed to step 4.
105#### Step 4: Accept Your Transfer
107If you were sent a point by a friend, then you should see a graphic under
108`Incoming Transfers`. Click the `Details ->` link under that graphic.
110Now you'll be on the management page of your point. The transfer isn't completed
111yet, so click `Accept incoming transfer`. Then check both boxes and and click
112their associated `Sign Transaction` and `Send Transaction` buttons.
114If you already own a point, then click on the `Details ->` under your sigil in the
115`Your Points` section.
117#### Step 5: Set Your Networking Keys
119If you just accepted a point, you'll be returned to your point screen. Notice that
120that links and buttons are now clickable. You now own this point!
122Click the link that says `Set Urbit networking keys`. Bridge will let you either
123download a keyfile derived from your networking keys are you can paste in your own
124network seed and derive a new keyfile. See our
125[HD Wallet Spec](https://github.com/urbit/proposals/blob/master/8.udon)
128It should be noted that this is an event on the Ethereum network and will cost
129a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
131#### Step 6: Generate Your Keyfile
133From the detail page associated with your point, click the `Generate Arvo Keyfile`
134button and you'll be taken to a page with a field titled `Network seed`. If you went
135through the address registration process, this should be filled in already.
136Click `Generate ->`, which will download a keyfile onto your machine.
138With that keyfile in hand, you can now exit Bridge.
142 ;div(id "arvo"): Installing Arvo
146Now you're ready to run Arvo. You're almost there!
148But first, some terminology:
149- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
150- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
152Arvo runs nicely on a Unix-like operating system -- Ubuntu,
153Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need
154to get one of the aforementioned systems. Don't worry: most of them are free.
156We have different installation instructions for different platforms. To install
157and run Arvo, run the commands that are listed for your operating system.
159On any platform, you can check your Arvo installation by running the `urbit`
160command. Installation was successful if you get a block of output that begins
164Urbit: a personal server operating function
173C compiler (gcc or clang)
192We recommend using the Homebrew package manager to run Arvo on MacOS.
198brew install gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl
199git clone https://github.com/urbit/urbit
203sudo ninja -C ./build/ meson-install
213sudo apt-get install g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev make openssl pkg-config python python3 python3-pip zlib1g-dev ninja-build
214sudo -H pip3 install --upgrade pip
215sudo -H pip3 install meson
217git clone https://github.com/urbit/urbit
221sudo ninja -C ./build/ install
231sudo 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
233# meson requires python 3.5; RHEL supplies wrong version
235 sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
236 sudo tar xzf Python-3.5.5.tgz
238 sudo ./configure --enable--optimizations
242 sudo ln -s python3.5 python3
246curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
247sudo /usr/local/bin/python3 get-pip.py
248# downgrade meson to avoid dependencies that redhat can't meet
249sudo -H /usr/local/bin/pip3 install meson
252git clone git://github.com/ninja-build/ninja.git && cd ninja
254./configure.py --boostrap
255sudo cp ./ninja /usr/local/bin
257git clone https://github.com/urbit/urbit
261sudo /usr/local/bin/ninja -C ./build/ install
271sudo pacman -S curl gcc git gmp libsigsegv ncurses ninja openssl python
272curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
273sudo python3 get-pip.py
274git clone https://github.com/urbit/urbit
278sudo ninja -C ./build/ meson-install
288sudo pkg install curl gcc git gmake gmp libsigsegv python python3 ncurses openssl gmp
289curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
290sudo python3 get-pip.py
291sudo -H pip install --upgrade pip
292sudo -H pip install meson
293sudo pkg install ninja
294git clone https://github.com/urbit/urbit
296sh ./scripts/bootstrap
298sudo ninja -C ./build/ meson-install
302##### Amazon Web Services
308sudo yum install gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel ncurses-devel openssl openssl-devel pkgconfig python2 python3 python3-pip wget git
309sudo env "PATH=$PATH" pip3 install --upgrade pip
310sudo env "PATH=$PATH" pip3 install meson
316wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
317wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
318sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
319sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm
321git clone git://github.com/ninja-build/ninja.git
324 ./configure.py --bootstrap
325 sudo cp ./ninja /usr/local/bin
329git clone https://github.com/urbit/urbit
333sudo env "PATH=$PATH" ninja -C ./build/ install
340Perhaps you want to boot a ship without an identity. We recommend doing that
341for development purposes, or if you just want to play around with an
342un-networked ship without getting a point. You can now use
343the command of the scheme below to boot a fake `~zod`.
349If you want to get on the Arvo network with your point, then continue to the
354 ;div(id "swap"): Set Up Swap
358If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, skip this section.
360Urbit wants to map 2GB of memory when it boots up. We won’t necessarily use all this memory, we just want 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.
362Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04). For Amazon there’s a StackOverflow thread [here](https://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).
364Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
368 ;div(id "boot"): Booting Your Ship
373Now the rubber meets the road. You'll be booting your ship with the keyfile
374that you downloaded from Bridge.
376#### Step 1: Find Your Point's Name
378This will look something like `~lodleb-ritrul`. You can see the name of your
379point(s) when you log into your wallet using the Bridge client.
381;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
383#### Step 2: Find the path to your keyfile
385Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
387#### Step 3: Run the boot command
389Type `cd` in your terminal to return to your home directory. If you want to
390store your ship somewhere besides your home directory, change the terminal's
391working directory to the desired directory.
393Run the command below, except with `~sample-planet` replaced by the name of your
394Urbit identity, and `path/to/my-planet.key` replaced with the path to your
398urbit -w sample-planet -k path/to/my-planet.key
401Or, if you'd prefer to copy your key in, you can run:
404urbit -w sample-planet -G rAnDoMkEy
407Either command will create a directory called `sample-planet/` and begin
408building your ship. It may take a few minutes.
410When your ship is finished booting, you will see the `~sample-planet:dojo>`
411prompt. At that point, you should permanently erase your keyfile from your
416 ;div(id "operation"): Basic Operations
420Welcome to your urbit! There's a few things you should do to become oriented.
424Let's try out the Dojo, the Arvo command line and Hoon REPL:
427~sample-planet:dojo> (add 2 2)
441Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
445~sample-planet:dojo> |mount %
454which indicates that the command was processed.
456`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
457Unix (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.
462Landscape is web app we built for chatting and making posts. We are using Landscape to run a few experimental "cities" -- private discussion communities -- as a closed beta of sorts. If you have an Azimuth point, you’ll need to [email us](mailto:support@urbit.org) a request to gain access to one of these cities.
464Once you're in a channel, you can also interact with it from the command line, if you so wish. Use `ctrl-x` in your ship's terminal window to toggle between the Dojo and the Talk prompts.
466#### Shutting Down and Restarting
468You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
470To 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