Operator's Manual/Running Urbit

Runtime Reference

The Urbit runtime is named Vere. It's the binary executable you use to run your ship (urbit on Linux and MacOS, urbit.exe on Windows). Vere manages your ship's pier, handles events, and runs the Nock virtual machine that performs your ship's computations.

Before version 1.9, Vere was split into two separate binaries: The urbit "king"/"urth" responsible for I/O and event persistence, and the urbit-worker "serf"/"mars" responsible for computations and state persistence. As of version 1.9, these have been merged into a single urbit (or urbit.exe) binary, though under the hood there's still two separate processes. The alternative king written in Haskell, urbit-king, has also been deprecated, so there's now only one binary.

Version 1.9 introduced a couple of new features. The first is the concept of "docking". When a new ship is booted, Vere will automatically copy itself into the pier, at [pier]/.bin/[pace]/vere-v[version]-[architecture]. It will also create a link to this file at [pier]/.run. This means that after the initial boot, the pier is self-contained and can be run with [pier]/.run, making the separate binary unnecessary. For older ships that were booted by a previous binary, v1.9 or later will not automatically perform this step, so it must be done with the dock utility (see below).

The pace mentioned in the path above is a new feature, and represents a release channel. At the time of writing, the default pace is live, which is for standard, stable releases. Alternative release channels will be introduced in the future, for things such as pre-release testing, nightly builds, etc. The pace is specified in a text file at [pier]/.bin/pace.

Along with docking, a binary upgrade feature has also been introduced. If you run the next utility (described below), Vere will check if there is a newer binary version available for the current pace. if there is, it will automatically be downloaded and installed. This means it's no longer necessary to go and manually download new binaries and swap them out, it's all managed inside the pier by Vere.

Common Usage

Boot comet

A comet is a kind of ship which may be quickly generated by anyone and which are virtually unlimited. They're useful as free identities for people to quickly try out Urbit.

To boot a comet, you just need to use the -c argument and specify the name for the pier (the pier is folder containing the ship's state and event log):

urbit -c some-pier-name

It will take a few minutes to bootstrap. Once complete, you'll be able to interact with the Dojo prompt and access the web interface in a browser.

When you eventually shut down the ship, the binary will copy itself into the pier, so in future you can run it by doing /path/to/pier/.run.

Boot ship

To boot a moon, planet, star or galaxy, you must use two arguments:

  • -w - the name of the ship (without the leading ~).
  • -k - the path to the key file which you downloaded from Bridge (or got from the parent planet and pasted into a file in the case of a moon).
urbit -w sampel-palnet -k /path/to/my.key

It will take a few minutes to bootstrap. Once complete, you'll be able to interact with the Dojo prompt and access the web interface in a browser.

If you want, you can use and additional -c option to specify a name for the pier. Without -c, the pier will be named the same as your ship. Note it's possible to use -G in lieu of -k and paste the private key directly in as an argument. This might be more convenient in the case of a moon.

When you eventually shut down the ship, the binary will copy itself into the pier, so in future you can run it by doing /path/to/pier/.run.

Run ship

If a ship has already been boostrapped, you can run it by simply specifying the pier:

urbit /path/to/pier

Alternatively, if the pier was booted by version 1.9 or later of the binary, or if you've previously run dock on the pier, you don't need a separate urbit binary and can just do /path/to/pier/.run to start the ship.

Boot fake ship

Development is often done on a "fake" ship rather than a real one. A fake ship has no connection to the real network, and uses fake keys so you don't actually need to own it. A fake ship can only talk to other fake ships on the same local machine.

To create one, you just use the -F option and specify the name of a ship (commonly a galaxy):

urbit -F zod

Compact State

Note the ship should be shut down before using either of the utilities described below.

Ships currently have a hard 2GB limit on the size of their state. Sometimes the state of long-running, heavily-used ships can exceed the 2GB limit and crash with a bail: meme error. To fix this, there are a couple of ways to reduce the size of the ship's state.

The first is the pack utility, which defragments the ship's snapshot. This usually only mildly compacts the state, but it is fast and uses little memory.

To run pack, you can do either urbit pack /path/to/pier or /path/to/pier/.run pack if it's been docked.

The second option is meld, which deduplicates the ship's snapshot. This can reduce the size much more significantly, sometimes by as much as half. This can use a lot of memory to complete, sometimes as much as 8GB, so if you don't have ample memory on your machine you might need to map some swap space.

To run meld, you can either do urbit meld /path/to/pier or /path/to/pier/.run meld if it's been docked.

If the meld succeeds, it'll print a memory report and exit. If it exits with KILLED, it means it ran out of memory and the meld was aborted.

Dock binary

From binary version 1.9 onwards, newly booted ships will have the binary automatically copied into their piers, so they can be run by doing /path/to/pier/.run. The means a separate binary is unnecessary, it's all contained in the pier. For existing ships booted before v1.9, you need to manually run the following command if you want this feature:

urbit dock /path/to/pier

Afterwards, you'll be able to just do /path/to/pier/.run and can delete the separate urbit binary.

If you see an error message that the link cannot be created, check that your file system allows hardlinks and you have permissions set to do so. (ExFAT file systems, used on some external hard drives, cannot create hardlinks.)

Update binary

From binary version 1.9 onwards, there is a mechanism to update the binary without having to go and download it yourself. Simply run urbit next /path/to/pier or /path/to/pier/.run next if docked. It will check if any newer binaries are available for your release channel and if there are, it'll automatically download the new one and install it in the pier.

Truncate event log

The event log of a ship is a totally ordered list of every single Arvo event that ship has undergone. The state of a ship is a pure function of the event log. In the event a ship's state checkpoint is corrupted, it can be rebuilt by replaying all the events in the log. In practice, event logs become large and unwieldy over time. They can reach many GB in size, and when they're very large it takes an impractically long time to replay them.

To reduce the size of the event log, the binary includes a chop utility. Chop wipes old events, and replaces them with a single event loading the whole current state of the ship. This drastically reduces the size of the log - typically down to less than a couple of GB from any larger size. Note this will irreversibly delete the old events, but most people don't need them anyway.

To chop an event log, first shut down your ship with ctrl+d or |exit in the Dojo. Next, run urbit chop /path/to/pier or /path/to/pier/.run chop if it's docked. You'll get an output that looks something like this:

loom: mapped 2048MB
boot: protected loom
live: loaded: MB/140.541.952
boot: installed 652 jets
loom: image backup complete
chop: event log truncation complete
      event log backup written to ~/piers/zod/.urb/log/chop/data_1-449.mdb.bak
      WARNING: ENSURE YOU CAN RESTART YOUR SHIP BEFORE DELETING YOUR EVENT LOG BACKUP FILE!
      if you can't, restore your log by running:
      `mv ~/piers/zod/.urb/log/chop/data_1-449.mdb.bak ~/piers/zod/.urb/log/data.mdb` then try again

At this point the event log has been truncated but a backup has been saved, so the size of the pier hasn't yet been reduced. Before deleting the backup, try booting your ship and make sure it runs fine. IT IS VERY IMPORTANT TO CHECK THIS. Assuming your ship boots fine, delete the backup in /path/to/pier/.urb/log/chop/data_XXXXX.mdb.bak.

If your ship failed to boot, you can restore the backup by moving it to /path/to/pier/.urb/log/data.mdb as described in Vere's print-out above.

Utilities

These utilities are not used to run ships, but perform operations on piers, print information about piers, or otherwise do useful things. Note the ship must be stopped to run any of these utilities on a pier. Some of these are utilities of the previously separate urbit-worker.

chop

Truncate the event log. Old events will be deleted and replaced with the current state of the ship. This can significantly reduce the size of the pier, but you won't be able to replay all events from the beginning (this shouldn't matter though).

You must shut down your ship before running this.

  • Undocked: urbit chop [pier]
  • Docked: [pier]/.run chop

This will save a backup of the event log to /path/to/pier/.urb/log/chop/data.XXXXX.mdb.bak when complete. Make sure your ship starts up again before deleting that backup file. If your ship fails to boot after running chop, move that .bak file back to /path/to/pier/.urb/log/data.mdb and try booting again.

cram

Jam the state of a ship. The jamfile will be saved in [pier]/.urb/roc/[current-event-number].jam. This creates a portable snapshot backup.

  • Undocked: urbit cram [pier]
  • Docked: [pier]/.run cram

dock

Copies the urbit binary into the target pier. The binary itself will be copied to [pier]/.bin/[pace]/vere-v[version]-[architecture]. The pace is a release channel. The default pace is live, for ordinary stable releases. The pace will also be recorded in a text file at [pier]/.bin/pace. Additionally, a link to the current binary will be created at [pier]/.run, which allows you to start a ship by calling [pier]/.run.

When a ship is newly booted by a runtime from v1.9 onwards, it will be automatically docked. For existing ships, it must be done explicitly with this command.

  • Undocked: urbit dock [pier]
  • Docked: [pier]/.run dock

Note the auto-dock behavior when booting new ships can be disabled with the --no-dock option.

eval

Evaluate a hoon expression without booting a ship.

The expression to evaluate is given in a string via stdin, and the result is pretty-printed to the terminal. Note you do not need to boot an actual ship to run this, the runtime can do it itself.

  • Undocked: echo [expression] | urbit eval
  • Docked: echo [expression] | [pier]/.run eval

This will work like:

> echo "(turn (limo 1 2 3 4 5 ~) succ)" | urbit eval
loom: mapped 2048MB
lite: arvo formula 11a9e7fe
lite: core 38d4ad4d
lite: final state 38d4ad4d
eval:
~[2 3 4 5 6]

grab

Measure memory usage analysis of a ship. The result will be printed to the terminal. This is the same output produced by running |mass in the Dojo.

  • Undocked: urbit grab [pier]
  • Docked: [pier]/.run grab

info

Print pier information.

  • Undocked: urbit info [pier]
  • Docked: [pier]/.run info
> urbit info zod
loom: mapped 2048MB
boot: protected loom
live: loaded: MB/268.173.312
boot: installed 351 jets


urbit: zod at event 256133
  disk: live=&, event=256133


lmdb info:
  map size: 1099511627776
  page size: 4096
  max pages: 268435456
  number of pages used: 1506786
  last transaction ID: 255733
  max readers: 126
  number of readers used: 0
  file size (page): 6171795456
  file size (stat): 6171795456

meld

Deduplicate ship state. This can significantly reduce memory usage for ships with large states. This is a common solution when ships use up all available mapped memory (currently 2GB) and crash with bail: meme.

Note this command may use a large amount of memory during execution, up to around 8GB or so, depending on the size of the ship's state and other factors. If you do not have enough memory to run it, you may need to allocate some swap.

If the meld succeeds, it will print out a memory usage report. If it exits saying KILLED, it means it ran out of memory and the operation was aborted.

  • Undocked: urbit meld [pier]
  • Docked: [pier]/.run meld

pack

Defragment a ship's state. This will reduce the size of a ship's state much less than meld, but it is much faster and requires much less memory to complete.

  • Undocked: urbit pack [pier]
  • Docked: [pier]/.run pack

prep

Prepare a pier for upgrade. This utility is designed to be a general-purpose forward-compatibility mechanism. What action (if any) is taken depends on the old version and new version. Currently, it just makes sure the snapshot is fully up-to-date.

  • Undocked: urbit prep [pier]
  • Docked: [pier]/.run prep

next

Request a runtime upgrade. If your binary is already the latest version, no action will be taken. If a new binary is available, it will be upgraded.

  • Undocked: urbit next [pier]
  • Docked: [pier]/.run next

queu AT-EVENT

Load a snapshot jamfile. AT-EVENT is an event number. There must be corresponding snapshot in [pier]/.urb/roc/[AT-EVENT].jam created previously with cram or -n.

  • Undocked: urbit queu [pier] 10000
  • Docked: [pier]/.run queu 10000

vere ARGS DIR

Download a binary. DIR is an output directory (it must already exist) and ARGS are:

  • -a, --arch ARCH - architecture, ARCH may be one of x86_64-linux, x86_64-darwin, x86_64-windows and aarch64-linux, though more may be added in the future.
  • -v, --version VER - version number, VER is e.g. 1.9.
  • -p, --pace - release channel, e.g. live.

Example usage:

  • Undocked: urbit vere -a x86_64-linux -v 1.9 -p live .

vile

Export keyfile.

The private keys of ship in the specified pier will be printed to the terminal.

  • Undocked: urbit vile [pier]
  • Docked: [pier]/.run vile

serf ARGS

Run as a 'serf' (as though it were the previously separate urbit-worker).

Note this utility is for kernel development purposes and has a programmatic interface, it does not have a user interface.

  • Undocked: urbit serf [pier] [key] [flags] [cache-size] [at-event]

Options

Below are all the options/flags/arguments that can be given to the urbit runtime.

-A, --arvo DIR

When booting a new ship, use directory DIR for the initial %base desk sync, rather than the one in the pill.

urbit -w sampel-palnet -k /path/to/my.key -A /path/to/arvo

-b, --http-ip IP

Bind the HTTP server to IP address IP.

  • Undocked: urbit -b 192.168.1.10 [pier]
  • Docked: [pier]/.run -b 192.168.1.10
> ss -tlnp | grep urbit
LISTEN 0      16         127.0.0.1:12321      0.0.0.0:*    users:(("urbit",pid=15689,fd=29))
LISTEN 0      16      192.168.1.10:8080       0.0.0.0:*    users:(("urbit",pid=15689,fd=28))

-B, --bootstrap PILL

When booting a new ship, use file PILL for the pill, rather than the default one fetched from https://bootstrap.urbit.org.

urbit -w sampel-palnet -k /path/to/my.key -B /path/to/the.pill

-c, --pier PIER

When booting a ship, name its pier as PIER rather than the usual @p.

  • Undocked: urbit -w sampel-palnet -k /path/to/my.key -c foobar

The pier folder will be named foobar as a result of the above command.

-C, --memo-cache-limit LIMIT

This sets the maximum number of entries for the memoization cache (used by the ~+ rune and a few other things). Zero means uncapped, otherwise the specified number of entries.

  • Undocked: urbit -C 50000 [pier]
  • Docked: [pier]/.run -C 50000

-d, --daemon

Run the ship in daemon mode. The process will be detached from the terminal (this implies -t).

  • Undocked: urbit -d [pier]
  • Docked: [pier]/.run -d

-e, --ethereum URL

Use the Ethereum gateway at URL rather than the default.

  • Undocked: urbit -e https://the.url [pier]
  • Docked: [pier]/.run -e https://the.url

-F, --fake SHIP

Boot a new fake development ship. Real networking is disabled, and instead the fake ship can only communicate with other fake ships on the local machine. This works for all ship classes except comets.

urbit -F zod

-g, --gc

Set GC flag, dumping garbage collector logs to stdout. This runs a GC pass at the end of every virtualized computation. This is intended as a runtime developer/QA tool for verifying refcounts. This currently only works if the binary was built with MEMORY_DEBUG (which changes allocation structures and produces incompatible snapshots).

  • Undocked: urbit -g [pier]
  • Docked: [pier]/.run -g

-G --key-string STRING

Boot a new ship with private key STRING.The private key is @uw format. See -k for an alternative.

  • Undocked: urbit -w sampel-palnet -G 0w50w.642KA.glYh8.RvaRp.6TA35.3XRYN.ULCI6.UmcsZ.5rGvG.3dvFt.E6rMF.mZnd~.3O6QB.7LZ1f.-ukYN.z2fcY.Ecviv.LiZEg.8w0sp

--http-port PORT

Set the HTTP port to PORT. This is the port you'd insecurely access Landscape on. Note this is for insecure HTTP only, see --https-port for HTTPS.

  • Undocked: urbit --http-port 8085 [pier]
  • Docked: [pier]/.run --http-port 8085

--https-port PORT

Set the HTTPS port to PORT. This is the port you'd securely access Landscape on. Note that this requires an SSL certificate to be configured, see the Configuring SSL guide for details. Note that if your ship is behind a reverse proxy (nginx, Caddy, etc) and an SSL certificate is configured there, you'd not usually enable HTTPS on the ship itself.

Note this is for secure HTTPS only, see --http-port for insecure HTTP.

  • Undocked: urbit --https-port 8443 [pier]
  • Docked: [pier]/.run --https-port 8443

-I, --inject FILE

Inject the event stored in FILE jamfile.

Note this has "full privileges" and can do anything to your ship. -I is for customization in hosting environments, and emergency recovery for sinking ships. Only run from trusted sources.

  • Undocked: urbit -I /path/to/file.jam [pier]
  • Docked: [pier]/.run -I /path/to/file.jam

-j, --json-trace

Create JSON trace files in [pier]/.urb/put/trace.

This runs a tracing profiler, and produces JSON output compatible with chrome://tracing.

  • Undocked: urbit -j [pier]
  • Docked: [pier]/.run urbit -j

-J, --ivory-pill PILL

This specifies an alternative Ivory pill to use. An Ivory pill is a pill compiled into the binary and used for runtime support code. You would not typically use this unless you're doing runtime or kernel development.

  • Undocked: urbit -J /path/to/ivory.pill [pier]
  • Docked: [pier]/.run -J /path/to/ivory.pill

-k, --key-file KEYS

Boot a new ship with the private key file KEY. See -G for an alternative.

  • Undocked: urbit -w sampel-palnet -k /path/to/my.key

-L, --local

Run a ship with local networking only. This will disable Ames networking, so the ship will not be able to communicate with other ships. HTTP(S) will continue to work as normal.

  • Undocked: urbit -L [pier]
  • Docked: [pier]/.run -L

--loom SIZE

Specify loom size (maximum memory usage).

The size is specified in exponents of 2. The default is 31 (2GB), minimum is 20 (1MB), and maximum is 33 (8GB).

  • Undocked: urbit --loom [size] [pier]
  • Docked: [pier]/.run --loom [size]

This can also be used with utilities like pack and meld. Note it must be specified after the utility like urbit pack --loom 32 ~/piers/zod .

-n, --replay-to NUMBER

Replay up to the specified event NUMBER.

  • Undocked: urbit -n 10000 [pier]
  • Docked: [pier]/.run -n 10000

A snapshot will be saved in a jamfile at [pier]/.urb/roc/[NUMBER].jam.

--no-conn

Disable the control pane unix socket.

  • Undocked: urbit --no-conn [pier]
  • Docked: [pier]/.run --no-conn

--no-dock

From v1.9 onwards, when a new ship is booted, the urbit binary will copy itself into the newly created pier by default (see the dock section for details). To prevent this from happening, the --no-dock option can be used.

  • Undocked: urbit --no-dock -w sampel-palnet -k /path/to/my.key

-p, --ames-port PORT

Set the Ames UDP port to PORT. This is the port used for inter-ship communications.

  • Undocked: urbit -p 33333 [pier]
  • Docked: [pier]/.run -p 33333

-P, --profile

Enable profiling. Profiles will be saved to [pier]/.urb/put/profile/[now].txt. This is useful for debugging and development. Profiling hit counters in Hoon code specified with the ~$ rune will be recorded here.

This runs a sampling profiler and produces custom output. Runtime cost metrics are only calculated if the binary was built with CPU_DEBUG.

  • Undocked urbit -P [pier]
  • Docked [pier]/.run -P

-q, --quiet

Run a ship without verbosity. This disables the output that the |verb command toggles. This is the opposite of -v. Verbosity can be enabled again by running |verb.

  • Undocked: urbit -q [pier]
  • Docked: [pier]/.run -q

-r, --replay-from NUMBER

Load snapshot at event NUMBER, only replay after that event. This lets you resume a partially completed replay. For the given NUMBER, there must be a corresponding snapshot in [pier]/.urb/roc/[NUMBER].jam, created by cram or -n.

  • Undocked: urbit -r 10000 [pier]
  • Docked: [pier]/.run -r 10000

-R, --versions

Report Vere build info.

> urbit -R
urbit 1.9
gmp: 6.2.1
sigsegv: 2.14
openssl: OpenSSL 1.1.1n  15 Mar 2022
libuv: 1.43.0
libh2o: 0.13.6
lmdb: 0.9.29
curl: 7.81.0
  • Undocked: urbit -R [pier]
  • Docked: [pier]/.run -R

-t, --no-tty

Disable terminal/TTY assumptions. With this set, there will be no Dojo prompt, and you'll only see debug messages from the runtime. This is similar to daemon mode (see -d), but the process will remain attached to the terminal in which it was run.

  • Undocked: urbit -t [pier]
  • Docked: [pier]/.run -t

-u, --bootstrap-url URL

Boot a new ship, using the pill fetched from URL rather than the default one.

  • Undocked: urbit -w sampel-palnet -k /path/to/my.key -u http://example.com/the.pill

--urth-loom SIZE

Specify the loom size (maximum memory usage) of the "king"/"urth" process.

The size is specified in exponents of 2. This is something you're unlikely to need to use as the "king"/"urth" process doesn't have a persistent state and doesn't need much memory. The --loom option, which sets the "serf"/"mars" memory size, is much more useful.

  • Undocked: urbit --urth-loom [size] [pier]
  • Docked: [pier]/.run --urth-loom [size]

-v, --verbose

Run a ship with verbose output. This is the same as what you get when you run |verb, and can be disabled by running |verb. This is the opposite of -q.

  • Undocked: urbit -v [pier]
  • Docked: [pier]/.run -v

-w, --name NAME

Boot a new ship with an Urbit ID of NAME. The NAME is the ordinary @p format but without the leading ~, so ~sampel-palnet is specified as sampel-palnet. This is typically used in conjunction with -k when booting a new ship.

  • Undocked: urbit -w sampel-palnet -k /path/to/my.key

-x, --exit

Run a ship but exist immediately after it starts.

  • Undocked: urbit -x [pier]
  • Docked: [pier]/.run -x

-X, --scry PATH

Read a ship's state on scry path PATH, jamming the result and saving it to [pier]/.urb/put/[PATH].jam. The scry path is in the format /[care]/[path], omitting the ship and case elements. For example, /cx/~zod/base/~2022.6.2..11.27.40..8f56/gen/code/hoon would be /cx/base/gen/code/hoon.

  • Undocked: urbit -X /cx/base/gen/code/hoon [pier]
  • Docked: [pier]/.run -X /cx/base/gen/code/hoon

-Y, --scry-info FILE

Optional name for the file produced by a scry performed with -X, rather than the scry path.

  • Undocked: urbit -X /cx/base/gen/code/hoon -Y foobar [pier]
  • Docked: [pier]/.run -X /cx/base/gen/code/hoon -Y foobar

-Z, --scry-format FORMAT

Optionally specify the output format for the file produced by a -X scry. The format may either be jam to produce a jam file, or else an aura. If it's an aura, the leading @ is omitted, so @ud is specified as ud. If an aura is specified, the resulting atom is encoded in a text file with that aura's formatting. If an aura is specified, the scry endpoint must produce an atom, not a cell.

  • Undocked: urbit -X /cx/base/gen/code/hoon -Z ud [pier]
  • Docked: [pier]/.run -X /cx/base/gen/code/hoon -Z ud