4 title/'Getting Started'
10This guide is broken into five parts:
12+ [Urbit Identities](#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"): Urbit Identities
27Urbit's identity layer, called Azimuth, is a public-key infrastructure (PKI)
28that uses the Ethereum blockchain. An Azimuth address, called a point,
29functions as an identity and
30a network address for Arvo, the Urbit OS. An instance of Arvo is called a
31*ship*. A ship can't use the Arvo network unless it's been booted with the keys
34Throughout this guide, we'll refer to \"Urbit identities\" and \"points\"
37Points are generally not freely available, so you will need to either
38purchase one or get one from a friend. To receive one, you will need an Ethereum
39wallet that supports the BIP39 mnemonic seed functionality, which allows you to
40access your wallet with a series of dictionary words.
41Hardware wallets, such as Ledger and TREZOR devices, satisfy this requirement.
42So do various web-based wallets.
44Once you have such a wallet, give your Ethereum address to the person who agreed
45to give you a point. Have them transfer the point to your address, and continue to the
50 ;div(id "bridge"): Using Bridge
54Bridge is a client for accessing and managing your Urbit identities.
55Importantly, Bridge also allows you to generate a keyfile that you will need to
56boot your ship so that it can use the Arvo network. Once you boot a ship
57with a keyfile, you can restart it later without the keyfile.
59*Note:* Bridge allows you to make _writes_ to the blockchain, but we ask you to confirm
60anything that will incur a transaction cost. If you plan to do anything heavy-duty, make
61sure your Ethereum address has some pocket ETH.
63Download Bridge [here](https://github.com/urbit/bridge/releases), and follow
64the instructions to run that program. Get a little bit of ETH on your address,
65enough for a couple of transactions.
67Once the program is running in your browser, go through each step according to
68what kind of wallet you have.
70### Accept Your Transfer
72After you access your Ethereum address, if a point was sent to that address,
73you'll come to a page that has an `Incoming Transfers` header, under which is
74a graphic. Click the `Details ->` link under that graphic.
76Now you'll be on the management page of your point. The transfer isn't completed
77yet, so click `Accept incoming transfer`. Then check both boxes and and click
78their associated `Sign Transaction` and `Send Transaction` buttons.
80If you already own a point, then click on the `Details ->` under your sigil in the
83### Set Your Networking Keys
85If you just accepted a point, you'll be returned to your point screen. Notice that
86that links and buttons are now clickable. You now own this point!
88Click the link that says `Set Urbit networking keys`. The field that is presented
89in the resulting page expects a 32-byte hexadecimal string; you can generate
90this data any way you please, but in the terminal on MacOS or Linux, you can write
93hexdump -n 32 -e '4/4 "%08X"' /dev/random
98It should be noted that setting your network keys is an event on the Ethereum network,
99and will therefore cost a trivial, but non-zero, amount of
100[gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
102### Generate Your Keyfile
104From the detail page associated with your point, click the `Generate Arvo Keyfile`
105link and you'll be taken to a page with a field titled `Network seed`. This
106field should already be filled in, and should match the hexadecimal string that you
107entered in the previous step. If its not filled in or does not match, fill it in
108with the correct string.
110Click `Generate ->`, which will download a keyfile onto your machine.
112With that keyfile in hand, you can now exit Bridge.
116 ;div(id "arvo"): Installing Arvo
120Now you're ready to run Arvo. You're almost there!
122But first, some terminology:
123- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
124- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
126Arvo runs nicely on a Unix-like operating system -- Ubuntu,
127Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need
128to get one of the aforementioned systems. Don't worry: most of them are free.
130We have different installation instructions for different platforms. To install
131and run Arvo, run the commands that are listed for your operating system.
133On any platform, you can check your Arvo installation by running the `urbit`
134command. Installation was successful if you get a block of output that begins
138Urbit: a personal server operating function
147C compiler (gcc or clang)
166We recommend using the Homebrew package manager to run Arvo on MacOS.
172brew install gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl
173git clone https://github.com/urbit/urbit
177sudo ninja -C ./build/ meson-install
187sudo 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
188sudo -H pip3 install --upgrade pip
189sudo -H pip3 install meson
191git clone https://github.com/urbit/urbit
195sudo ninja -C ./build/ install
205sudo 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
207# meson requires python 3.5; RHEL supplies wrong version
209 sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
210 sudo tar xzf Python-3.5.5.tgz
212 sudo ./configure --enable--optimizations
216 sudo ln -s python3.5 python3
220curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
221sudo /usr/local/bin/python3 get-pip.py
222# downgrade meson to avoid dependencies that redhat can't meet
223sudo -H /usr/local/bin/pip3 install meson
226git clone git://github.com/ninja-build/ninja.git && cd ninja
228./configure.py --boostrap
229sudo cp ./ninja /usr/local/bin
231git clone https://github.com/urbit/urbit
235sudo /usr/local/bin/ninja -C ./build/ install
245sudo pacman -S curl gcc git gmp libsigsegv ncurses ninja openssl python
246curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
247sudo python3 get-pip.py
248git clone https://github.com/urbit/urbit
252sudo ninja -C ./build/ meson-install
262sudo pkg install curl gcc git gmake gmp libsigsegv python python3 ncurses openssl gmp
263curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
264sudo python3 get-pip.py
265sudo -H pip install --upgrade pip
266sudo -H pip install meson
267sudo pkg install ninja
268git clone https://github.com/urbit/urbit
270sh ./scripts/bootstrap
272sudo ninja -C ./build/ meson-install
276#### Amazon Web Services
282sudo yum install gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel ncurses-devel openssl openssl-devel pkgconfig python2 python3 python3-pip wget git
283sudo env "PATH=$PATH" pip3 install --upgrade pip
284sudo env "PATH=$PATH" pip3 install meson
290wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
291wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
292sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
293sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm
295git clone git://github.com/ninja-build/ninja.git
298 ./configure.py --bootstrap
299 sudo cp ./ninja /usr/local/bin
303git clone https://github.com/urbit/urbit
307sudo env "PATH=$PATH" ninja -C ./build/ install
314Perhaps you want to boot a ship without an identity. We recommend doing that
315for development purposes, or if you just want to play around with an
316un-networked ship without getting a point. You can now use
317the command of the scheme below to boot a fake `~zod`.
323If you want to get on the Arvo network with your point, then continue to the
328 ;div(id "swap"): Set Up Swap
332If 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.
334Urbit 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.
336Digital 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).
338Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
342 ;div(id "boot"): Booting Your Ship
347Now the rubber meets the road. You'll be booting your ship with the keyfile
348that you downloaded from Bridge.
350### Step 1: Find Your Point's Name
352This will look something like `~lodleb-ritrul`. You can see the name of your
353point(s) when you log into your wallet using the Bridge client.
355;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");
357### Step 2: Find the path to your keyfile
359Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
361### Step 3: Run the boot command
363Type `cd` in your terminal to return to your home directory. If you want to
364store your ship somewhere besides your home directory, change the terminal's
365working directory to the desired directory.
367Run the command below, except with `~sample-planet` replaced by the name of your
368Urbit identity, and `path/to/my-planet.key` replaced with the path to your
372urbit -w ~sample-planet -k path/to/my-planet.key
375Or, if you'd prefer to copy your key in, you can run:
378urbit -w ~sample-planet -G rAnDoMkEy
381Either command will create a directory called `sample-planet/` and begin
382building your ship. It may take a few minutes.
384When your ship is finished booting, you will see the `~sample-planet:dojo>`
385prompt. At that point, you should permanently erase your keyfile from your
390 ;div(id "operation"): Basic Operations
394Welcome to your urbit! There's a few things you should do to become oriented.
398Let's try out the Dojo, the Arvo command line and Hoon REPL:
401~sample-planet:dojo> (add 2 2)
415Clay, the Arvo filesystem, isn't mounted to Unix by default. Switch to the Dojo
419~sample-planet:dojo> |mount %
428which indicates that the command was processed.
430`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in
431Unix (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.
435Landscape is web app we built for chatting and making posts on the Urbit network using the Hall messaging protocol. In the future we plan to use Landscape to run a few experimental "cities" -- private discussion communities -- as a closed beta of sorts. If you have an Azimuth point and you'd like to be involved, let us know [by email](mailto:support@urbit.org).
439If you've successfully booted your Urbit, you can access a support channel we run on the network at `~dopzod/urbit-help`. To join, type `ctrl-x` in your ship's terminal window to toggle between the Dojo and the Talk prompts, then enter the command `;join ~dopzod/urbit-help`.
441### Shutting Down and Restarting
443You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
445To 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