This site has been deprecated. Go to docs.urbit.org.
Urbit Developers

Overview

How to use this site

This site is intended for developers who want to learn how Urbit works from the inside out and how to build and deploy apps. If you are new to the platform, start with Hoon School and App School I and II. Complete documentation for the Hoon language and the standard library are included.

Hoon is a powerful and expressive language which builds on the Urbit platform to promote complete app interoperability and user control. We believe you'll find it to be a pleasantly innovative approach to thinking about how computation works and what a development experience should be.

If you are a regular Urbit user (rather than a developer), you will find operational instructions on the main site.

Instructions for operators (hosting providers, power users, etc.) are hosted on the operators site.

Primer

Urbit application development involves a client/server stack, where Urbit is the server and the client can be any normal interface. Unlike other servers, Urbit is also an entire operating system and ACID datastore. The Urbit OS includes a filesystem, encrypted P2P network, timer, application sandbox, software distribution mechanism, built-in identity layer (Urbit ID), and HTTP server. This means that you can build and distribute production-grade applications without dealing with Linux, databases, authentication systems, devops, or proprietary app stores.

Clients that interact with Urbit can be web browsers, mobile or desktop applications, command lines, or anything else that presents a user interface. At time of writing, most clients communicate with Urbit over HTTP by sending JSON back and forth, primarily via pub/sub APIs.

Where Urbit differs from other client/server stacks is that all users run their own servers (urbits), and those servers talk directly to one another. Because those servers are also databases, all users store their own data, which they exchange with one another based on application-level logic.

Urbit allows programmers to create what are called agents, which can be thought of as individual microservices—each one contains its own logic, defines its own API, can be started and stopped, can interact with the rest of the operating system and other agents, and is responsible for storing its own data. The lifecycle of agents is managed by the part of the operating system called Gall.

Since Urbit is actually an operating system, not just a server, when we talk about an Urbit “application” we could mean any of several things:

  • A web or mobile interface that interacts with one or more agents to define something that looks a lot like an “app”
  • A single agent that runs in the background
  • A script called a generator that’s executed from Urbit’s own command-line shell (called the dojo)

Generators, agents and supporting code are packaged up into desks. These provide a mechanism for packaging up related code, and can be shared directly with other users over the network—this is how software distribution works on Urbit.

All Urbit-side code is written in a purely functional and statically typed language called Hoon. Hoon looks kind of strange compared to most other programming languages, primarily because it’s based on runes rather than keywords. This strangeness is due to unfamiliarity rather than any form of essential complexity, in much the same way as Chinese appears more complex to an English-speaker than, say, Spanish.

It’s possible to develop for Urbit without learning Hoon by learning its client-side HTTP interface; however, investing the time to learn Hoon will make you a far more capable Urbit developer.

Core Components

Arvo

Urbit's purely functional OS, written in Hoon, that serves as the event manager of your urbit

Azimuth

A general-purpose public-key infrastructure (PKI) on the Ethereum blockchain

Hoon

A strictly typed functional programming language that compiles itself to Nock

Nock

A low-level homoiconic combinator language

Dojo

Dojo is a system for operating on and transforming data in Urbit

Vere

The Nock runtime environment and Urbit Virtual Machine