Runtime Reference

The Urbit runtime is named Vere. It's the binary executable you use to run your ship. 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 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.

Pace

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 represents a release channel. The default pace is live, which is for standard, stable releases. There is also soon for pre-release candidates, and edge for unstable development builds (dangerous). 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 keyfile.

The name of the .key file will vary slightly depending on where you got it from.

./urbit -w sampel-palnet -k /path/to/sampel-palnet.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 ./urbit dock <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 default 2GB limit on the size of their state, which can be increased with the --loom flag. 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.

Pack

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.

Meld

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 RAM to complete, sometimes as much as 8GB, so if you don't have ample RAM 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.) Also note that this command will fail if the docked runtime already exists.

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 download the new one and install it in the pier. You can run the newly-installed runtime with /path/to/pier/.run.

Set memory size

Vere includes the --loom option, which allows you to set the size of the loom (the memory area where the current ship state and computation state are stored). This is specified in exponents of two, so 1GB is 30 (2^30 = ~1GB), 2GB is 31 (2^31 = ~2GB), 4GB is 32 (2^32 = ~4GB), and 8GB is 33 (2^33 = ~8GB).

The default loom size is 2GB (31), and maximum is currently 8GB (33). It can be set much lower, but below 2GB you'll likely have problems with running out of memory.

Note the specified memory size must be entirely available. If it isn't (for example, you specify 33 (8GB) but only have 6GB available), it will fail to boot. The best approach in that scenario is to allocate some swap space to make up the difference. Indeed, on memory-constrained systems, it's almost always preferable to use swap rather than set the loom very low and crash your ship when it runs out of memory.

Note also that setting the loom size above the 2GB default will allow the persistent state of your ship to grow larger than 2GB. If that happens, you won't be able to use the default size anymore, and will have to set a larger loom every time you boot it, unless you can reduce it back below 2GB with tools like pack and meld.

See the --loom entry for further usage details.

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.

In older versions of Vere, all events were stored in a single continuous event log file. Recently, the "epoch" system was introduced, where a separate, independent file is periodically created for new events - usually upon upgrade of the runtime. These separate event log portions are called epochs.

To reduce the total size of the event log, the binary includes a chop utility to delete epochs older than the latest two.

To chop the 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.

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 by deleting old epochs (event log segments).

Epochs older than the two latest will be deleted. This can significantly reduce the size of the pier, but you won't be able to replay all events from the very beginning (this shouldn't matter though).

You must shut down your ship before running this.

• Undocked: ./urbit chop [pier]

• Docked: [pier]/.run chop

You'll get an output that looks something like this:

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/425.787.392
live: loaded: KB/16.384
boot: installed 967 jets
disk: loaded epoch 0i95037
chop: deleting epoch 0i346
chop: deleting epoch 0i0
chop: event log truncation complete

If there are two or fewer epochs, chop won't do anything. Additionally, if most of the event log data is contained in the latest two epochs, chop won't be very effective at reducing its size.

In order to create new epochs, and therefore shunt existing ones towards being removed by chop, you can use the roll utility before chopping.

cram

Create a backup snapshot of the ship.

The jamfile will be saved in [pier]/.urb/roc/[current-event-number].jam.

• Undocked: ./urbit cram [pier]

• Docked: [pier]/.run cram

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/503.791.616
live: loaded: KB/16.384
boot: installed 1362 jets
disk: loaded epoch 0i355
urbit: cram: preparing
hash-cons arena:
  root: B/160
  atoms (507080):
    refs: MB/10.284.580
    data: MB/156.910.873
    dict: MB/25.424.880
  total: MB/192.620.333
  cells (9746385):
    refs: MB/298.607.040
    dict: MB/738.197.200
  total: GB/1.036.804.240
total: GB/1.229.424.733

urbit: cram: rock saved at event 405

dock

Copy 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

dock: pace (live): configured at zod/.bin/pace
vere: binary copy succeeded

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

eval

Evaluate a Hoon expression without booting a ship.

The expression to evaluate is given in a string, and the result is pretty-printed to the terminal. Note that 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 by default) 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

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/374.538.240
live: loaded: KB/16.384
boot: installed 1362 jets
disk: loaded epoch 0i887
hash-cons arena:
  root: B/160
  atoms (225113):
    refs: MB/6.356.220
    data: MB/146.816.424
    dict: MB/15.713.440
  total: MB/168.886.084
  cells (7530958):
    refs: MB/184.549.300
    dict: MB/738.197.200
  total: MB/922.746.500
total: GB/1.091.632.744

urbit: meld: gained: MB/41.238.216

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

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/398.344.192
live: loaded: KB/16.384
boot: installed 1362 jets
disk: loaded epoch 0i887
urbit: pack: gained: MB/23.806.504

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

boot: home is zod
disk: loaded epoch 0i355
loom: mapped 2048MB
boot: protected loom
live: mapped: MB/403.128.320
live: loaded: KB/16.384
boot: installed 1362 jets
loom: image backup complete
disk: created epoch 405
loom: mapped 2048MB
lite: arvo formula 4ce68411
lite: core 641296f
lite: final state 641296f
disk: loaded epoch 0i405
loom: mapped 2048MB
boot: protected loom
live: mapped: MB/403.128.320
live: loaded: KB/16.384
boot: installed 1362 jets
vere: ready for upgrade

next

Upgrade the pier's runtime.

If the pier's runtime is already the latest version, no action will be taken. If a new runtime version is available, it will be upgraded.

• Undocked: ./urbit next [pier]

• Docked: [pier]/.run next

~
urbit 3.2
boot: home is zod
disk: loaded epoch 0i887
loom: mapped 2048MB
boot: protected loom
live: mapped: MB/347.766.784
live: loaded: KB/16.384
boot: installed 1362 jets
loom: mapped 2048MB
lite: arvo formula 4ce68411
lite: core 641296f
lite: final state 641296f
disk: loaded epoch 0i887
loom: mapped 2048MB
boot: protected loom
live: mapped: MB/347.766.784
live: loaded: KB/16.384
boot: installed 1362 jets
vere: next (%live): 3.4
vere: saved to zod/.bin/live/vere-v3.4-macos-aarch64
vere: upgrade succeeded

You can run the pier's upgraded runtime with /path/to/pier/.run.

queu AT-EVENT

Load a backup snapshot.

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

roll

Create a new epoch.

An epoch is a discrete, separate portion of the event log. This is useful in combination with chop, to reduce the size of the event log on disk.

• Undocked: ./urbit roll [pier]

• Docked: [pier]/.run roll

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/347.766.784
live: loaded: KB/16.384
boot: installed 1362 jets
disk: loaded epoch 0i887
loom: image backup complete
disk: created epoch 5886

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 linux-x86_64, linux-aarch64, macos-aarch64, or macos-x86_64. More may be added in the future.

• -v, --version VER - version number, VER is e.g. 3.4.

• -p, --pace - release channel, e.g. live.

Example usage:

./urbit vere -a macos-aarch64 -v 3.4 -p live .

Results in...

vere: saved to ./vere-v3.4-macos-aarch64
vere: download succeeded

vile

Export a keyfile.

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

• Undocked: ./urbit vile [pier]

• Docked: [pier]/.run vile

loom: mapped 2048MB
boot: protected loom
live: mapped: MB/403.128.320
live: loaded: KB/16.384
boot: installed 1362 jets
0w50w.642KA.glYh8.RvaRp.6TA35.3XRYN.ULCI6.UmcsZ.5rGvG.3dvFt.E6rMF.mZnd~.3O6QB.7LZ1f.-ukYN.z2fcY.Ecviv.LiZEg.8w0sp

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.

./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

Linux

$ 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))

macOS

$ lsof -nP -iTCP | grep urbit
urbit      4841 admin 29u  IPv4 0x6e1dcf159955111b      0t0  TCP 127.0.0.1:8080 (LISTEN)
urbit      4841 admin 31u  IPv4  0x16fd2f165413aca      0t0  TCP 127.0.0.1:12321 (LISTEN)

-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 sampel-palnet etc.

./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

Set the maximum number of entries for the memoization cache.

This cache is used by the ~+ rune and a few other things.

An argument 0 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

You can kill this process by running kill -9 [pid]. You can find the PID with ss or lsof; alternatively, you can attempt to run the ship again, then you'll get a warning from the runtime like pier: locked by PID [pid].

-e, --ethereum URL

Use the Ethereum RPC node 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.

./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 backup snapshot.

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

Specify 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.

./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 backup snapshot will be saved 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

Prevent the urbit binary from copying itself into the new pier.

./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 without turning off the ship 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.

• Undocked: ./urbit -R [pier]

• Docked: [pier]/.run -R

This reports the version numbers for the runtime and its dependencies.

urbit 3.4
gmp: 6.2.1
sigsegv: 2.14
openssl: OpenSSL 1.1.1w  11 Sep 2023
libuv: 1.50.0
libh2o: 0.13.6
lmdb: 0.9.29
curl: 8.9.1

-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.

./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.

./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