2title = "Technical overview"
7Urbit is a clean-slate software stack designed to implement an encrypted P2P
8network of general-purpose personal servers. Each server on this network is a
9deterministic computer called an 'urbit' that runs on a Unix-based virtual
12The current Urbit stack includes (among other things):
14- Arvo: the functional operating system of each urbit, written in Hoon.
15- Azimuth: the Urbit identity layer, built on the Ethereum blockchain.
16- Hoon: a strictly typed functional programming language whose standard library
17 includes a Hoon-to-Nock compiler.
18- Nock: a low-level combinator language whose formal specification fits readably on a t-shirt.
19- Vere: a Nock interpreter and Unix-based virtual machine that mediates between
20 each urbit and the Unix software layer.
22## Anatomy of a personal server
24Your urbit is a deterministic computer in the sense that its state is a pure
25function of its event history. Every event in this history is a
26[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your
27urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).
29Because each urbit is deterministic we can describe its role appropriately in
30purely functional terms: it maps an input event and the old urbit state to a
31list of output actions and the subsequent state. This is the Urbit transition
35<input event, old state> -> <output actions, new state>
38For example, one input event could be a keystroke from the terminal, say
39`[enter]` after having already typed `(add 2 2)`; and an output action could be
40to print in the terminal window the resulting value of a computation performed
41when the user hit `[enter]`, in this case `4`. The input event is stored in the
44Events always start from outside of your urbit, whether they're local to the
45computer running the urbit (e.g., a keystroke in the terminal) or they originate
46elsewhere (e.g., a packet received from another urbit). When an event is
47processed, various parts of the urbit state can be modified before the resulting
48list of output actions is returned.
50Can output actions from your urbit cause side-effects in the outside world?
51The answer had better be "yes," because a personal server without side effects
52isn't useful for much. In another sense the answer had better be "no," or else
53there is a risk of losing functional purity; your urbit cannot _guarantee_ that
54the side effects in question actually occur. What's the solution?
57[sandboxed](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) in a
58virtual machine, Vere, which runs on Unix. Code running in your urbit cannot
59make Unix system calls or otherwise directly affect the underlying platform.
60Strictly speaking, internal urbit code can only change internal urbit state; it
61has no way of sending events outside of its runtime environment. Functional
64In practical terms, however, you don't want your urbit to be an impotent
65[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why
66Vere also serves as the intermediary between your urbit and Unix. Vere observes
67the list of output events, and when external action is called for makes the
68appropriate system calls itself. When external events relevant to your urbit
69occur in the Unix layer, Vere encodes and delivers them as input events.
73Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking)
74OS, written in Hoon, that serves as the event manager of your urbit.
75It can upgrade itself from over the network without downtime. The Arvo kernel
76proper is quite simple -- it's only about 600 lines of code, excluding its
79The Urbit transition function is implemented in Arvo. Upon being 'poked' by
80Vere with the pair of `<input event, state>`, Arvo directs the event to the
81appropriate OS module. The result of each Vere 'poke' is a pair of
82`<output events, new state>`. Events are typed, and each has an explicit
83call-stack structure indicating the event's source module in Arvo.
85Arvo modules are also called 'vanes'. Arvo's vanes are:
87- Ames: defines and implements Urbit's encrypted P2P network protocol, as well
88 as Urbit's identity protocol.
89- Behn: manages timer events for other vanes.
90- Clay: global, version-controlled, and referentially-transparent file system.
91- Dill: terminal driver.
92- Eyre: HTTP web client and server.
93- Ford: typed functional build system.
94- Gall: application sandbox and manager.
95 - Dojo (app): Shell and Hoon REPL.
96 - Talk (app): Chat client.
100Hoon is a strictly typed functional programming language that compiles itself
101to Nock and is designed to support higher-order functional programming without
102requiring knowledge of category theory or other advanced mathematics. Haskell
103is fun but it isn't for everybody.
105Hoon aspires to a concrete, imperative feel. To discourage the creation of
106write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead
107of keywords. The type system infers only forward and does not use unification,
108but is not much weaker than Haskell's. The compiler and inference engine is
109about 3000 lines of Hoon.
113Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)
114combinator language. It's so simple that its [specification](@/docs/tutorials/nock/definition.md)
115fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions
116are more narrow. Most Lisps are one-layer: a practical language is to be
117created by extending a theoretically simple interpreter. The abstraction is
118simple and the implementation is practical. Unfortunately it's far more difficult
119to enforce both simplicity and practicality in an actual Lisp codebase. Hoon
120and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the
121simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it
122can upgrade Hoon over the network without downtime.
124The Nock data model is quite simple. Every piece of data is a 'noun'. A noun
125is an atom or a cell. An atom is any unsigned integer. A cell is an ordered
126pair of nouns. Nouns are acyclic and expose no pointer equality test.
130Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on
131Unix, and is the intermediate layer between your urbit and Unix. As noted
132earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode
133and deliver relevant external events to Arvo. Vere is also responsible for
134implementing jets and maintaining the persistent state of each urbit.
136In principle, Vere keeps a comprehensive log of every event from the time you
137initially booted your urbit. What happens if the physical machine loses power
138and your urbit's state is 'lost' from memory? When your urbit restarts it will
139replay its entire event history and totally recover its latest state from
142In practice, event logs become large and unwieldy over time. Periodically a
143snapshot of the permanent state is taken and the logs are pruned. You're still
144able to rebuild your state in case of power outage, down to the last keystroke.
146Vere is not essential to the Urbit stack; one can imagine using Urbit on a
147hypervisor, or even bare metal. One member of the community is even working on
148an independent implementation of Urbit using Graal/Truffle on the JVM.
150The Urbit stack (compiler, standard library, kernel, modules, and applications,
151but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT
156Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum
157blockchain, used as a decentralized ledger for what are known as **Urbit
158identities**, or simply **identities**. Having an identity is necessary to use
159the Urbit network, which makes it important to have a neutral ledger to
160determine who owns what.
162Azimuth is not, however, part of the Urbit stack. Azimuth is a parallel system
163that can be used as a generalized identity system for other projects. Azimuth
164"touches" the Urbit ecosystem when an Urbit identity is used to boot a virtual
165computer on the Arvo network for the first time. When that happens, the identity
166considered **linked** to Azimuth and the identity's full powers are available
167for use. Once an identity is linked, it cannot be unlinked.
169A metaphor might make the relationship between these two systems to understand:
170Azimuth is the bank vault that stores the deed to your house. The Urbit network
171is the neighborhood that you live in.
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