Developer's Guide

There are roughly two kinds of development on Urbit: core development and application development. Urbit applications are still young, but can be fun to experiment with. The kernel is much more stable, but generally more challenging from an engineering standpoint.

This guide will start by getting you set up to run an Urbit ship, and then tell you everything you need to know to do either.

Setting up your environment

We assume you’ve gotten a basic introduction to Urbit. If you haven’t, read the Understanding Urbit series.

Once you’re ready, you can get started on the network right away and take some first steps, without acquiring an identity, by creating a comet.

When developing, however, we recommend booting a development ship and working locally -- you may need to make changes that could, in the wrong hands, destroy the ship’s environment, and it’s best to do so in a safe, separate place.

Core development

Working on the core means improving the Urbit project itself, working with the existing community of Urbit developers.

Just arrived and unsure what to work on? An ideal way to get started is by experimenting with the system, talking to other developers, and reading (or contributing to) the documentation.

Prefer learning with an instructor? We also offer an online course that covers the basics of Urbit development called Hoon School. If course-based learning works well for you, we recommend you sign up.

The Urbit developer community congregates around the urbit-dev mailing list, the ~/~dopzod/urbit-help channel on Landscape, and Urbit’s GitHub repository. It’s a good idea to sign up, see what people are talking about, and introduce yourself.

Once you’re comfortable working with Urbit, check out the project’s issues on GitHub or some of our contribution bounties.

If you’re looking for some guidance, need help, or would prefer direct communication for your ideas, you can also always reach out to us directly at

Application development

When creating user applications on Urbit, you aren’t tied to any particular user interface. They can work without providing a response to the user, or by printing to the Dojo, or with an interface in Landscape, which uses Eyre (the Arvo vane that serves HTTP to serve a React-based interface to the application through a web browser).

When writing applications, you will often make use of Gall, the Arvo vane that manages user applications.

If you want to see examples of Urbit applications with common functionality requirements, you can see our examples repository. If you want to get started building applications with a Landscape interface, check out our create-landscape-app repository.

Creating a development ship

To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.

Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have installed our software.

To create a fake ship named ~zod, run the command below. You can replace zod with any valid Urbit ship-name.

./urbit -F zod

Now you should see a block of boot messages, starting with the Urbit version number. Welcome!

Community tutorials

Here are some tutorials written by members of the Urbit community. Some are a little outdated, but they may still prove useful.

If you want to add something to the list, shoot us an email or make a pull request in the docs repository.

How else can I contribute?

The Urbit project is a global community of developers, users, and fans. If you’re interested in getting involved, there’s space for you; you don’t have to be a developer to be a part of the project.

Running stars and galaxies

There are two ways to participate in the Arvo network: as a user running a planet and as an infrastructure provider running a galaxy or a star.

For planets, Urbit is a peer-to-peer network where users can interact with each other via Landscape, or using custom applications that anyone can write.

Running a planet helps build Urbit’s community, surfaces bugs, and helps core developers improve Urbit under realistic conditions.

Stars and galaxies, however, have additional responsibilities and play a role in peer discovery as well as star and planet distribution. You can think of stars and galaxies as similar to the DNS system in the modern Internet. Most users don’t know it exists, but without it, the web wouldn’t work at all.

Running a reliable galaxy or star, and spawning stars and planets from them, are excellent ways to help bootstrap the Urbit network.

If you’re interested in running a galaxy or star, you’ll be reliably providing peer discovery for your children just by running your node – and we’re doing our best to make this both easy and profitable. If you’re interested in this, see Star and Galaxy Operations.

If you’re interested in distributing planets, read on.

Distribute points

Want to get your friends and family into Urbit? Distribute planets using Bridge with a feature called delegated sending.

Here’s how it works: any star can grant a number of invites to any of its child planets. Those planets can then send one-time-use invite codes via email to anyone of their choosing.

For instructions on how to grant and send invites, check out Using Bridge.