# 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 <a href="#pace" id="pace"></a>

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](#dock)).

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](#next)), 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 <a href="#common-usage" id="common-usage"></a>

### Boot comet <a href="#boot-comet" id="boot-comet"></a>

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

```sh
./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 <a href="#boot-ship" id="boot-ship"></a>

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.

```sh
./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 <a href="#run-ship" id="run-ship"></a>

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

```sh
./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 <a href="#boot-fake-ship" id="boot-fake-ship"></a>

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

```sh
./urbit -F zod
```

### Compact State <a href="#compact-state" id="compact-state"></a>

**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`](#--loom-size) 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 <a href="#pack" id="pack"></a>

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 <a href="#meld" id="meld"></a>

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 <a href="#dock-binary" id="dock-binary"></a>

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:

```sh
./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 <a href="#update-binary" id="update-binary"></a>

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 <a href="#set-memory-size" id="set-memory-size"></a>

Vere includes the [`--loom`](#--loom-size) 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`](#pack) and [`meld`](#meld).

See the [`--loom`](#--loom-size) entry for further usage details.

### Truncate event log <a href="#truncate-event-log" id="truncate-event-log"></a>

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`](#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 <a href="#utilities" id="utilities"></a>

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` <a href="#chop" id="chop"></a>

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`](#roll) utility before chopping.

### `cram` <a href="#cram" id="cram"></a>

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` <a href="#dock" id="dock"></a>

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` <a href="#eval" id="eval"></a>

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:

```sh
$ 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` <a href="#grab" id="grab"></a>

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` <a href="#info" id="info"></a>

Print pier information.

* Undocked: `./urbit info [pier]`
* Docked: `[pier]/.run info`

```sh
$ ./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` <a href="#meld" id="meld"></a>

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` <a href="#pack" id="pack"></a>

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` <a href="#prep" id="prep"></a>

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` <a href="#next" id="next"></a>

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` <a href="#queu-at-event" id="queu-at-event"></a>

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` <a href="#roll" id="roll"></a>

Create a new epoch.

An epoch is a discrete, separate portion of the event log. This is useful in combination with [`chop`](#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` <a href="#vere-args-dir" id="vere-args-dir"></a>

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:

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

Results in...

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

### `vile` <a href="#vile" id="vile"></a>

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` <a href="#serf-args" id="serf-args"></a>

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.

```sh
./urbit serf [pier] [key] [flags] [cache-size] [at-event]
```

## Options <a href="#options" id="options"></a>

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

### `-A, --arvo DIR` <a href="#a---arvo-dir" id="a---arvo-dir"></a>

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

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

### `-b, --http-ip IP` <a href="#b---http-ip-ip" id="b---http-ip-ip"></a>

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

```sh
$ 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

```sh
$ 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` <a href="#b---bootstrap-pill" id="b---bootstrap-pill"></a>

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

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

### `-c, --pier PIER` <a href="#c---pier-pier" id="c---pier-pier"></a>

When booting a ship, name its pier as `PIER` rather than the usual `sampel-palnet` etc.

```sh
./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` <a href="#c---memo-cache-limit-limit" id="c---memo-cache-limit-limit"></a>

Set the maximum number of entries for the memoization cache.

This cache is used by the [`~+`](https://docs.urbit.org/hoon/rune/sig#siglus) 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` <a href="#d---daemon" id="d---daemon"></a>

Run the ship in daemon mode.

The process will be detached from the terminal (this implies [`-t`](#t---no-tty)).

* 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` <a href="#e---ethereum-url" id="e---ethereum-url"></a>

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` <a href="#f---fake-ship" id="f---fake-ship"></a>

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.

```sh
./urbit -F zod
```

### `-g, --gc` <a href="#g---gc" id="g---gc"></a>

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` <a href="#g---key-string-string" id="g---key-string-string"></a>

Boot a new ship with private key `STRING`.

The private key is [`@uw`](https://docs.urbit.org/build-on-urbit/hoon-school/e-types#what-auras-are-there) format. See [`-k`](#k---key-file-keys) for an alternative.

```sh
./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` <a href="#http-port-port" id="http-port-port"></a>

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`](#https-port-port) for HTTPS.

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

### `--https-port PORT` <a href="#https-port-port" id="https-port-port"></a>

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](https://docs.urbit.org/os/basics#configuring-ssl) 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`](#http-port-port) for insecure HTTP.

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

### `-I, --inject FILE` <a href="#i---inject-file" id="i---inject-file"></a>

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` <a href="#j---json-trace" id="j---json-trace"></a>

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` <a href="#j---ivory-pill-pill" id="j---ivory-pill-pill"></a>

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` <a href="#k---key-file-keys" id="k---key-file-keys"></a>

Boot a new ship with the private key file `KEY`.

See [`-G`](#g---key-string-string) for an alternative.

```sh
./urbit -w sampel-palnet -k /path/to/my.key
```

### `-L, --local` <a href="#l---local" id="l---local"></a>

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` <a href="#loom-size" id="loom-size"></a>

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`](#pack) and [`meld`](#meld). Note it must be specified *after* the utility like `./urbit pack --loom 32 ~/piers/zod` .

### `-n, --replay-to NUMBER` <a href="#n---replay-to-number" id="n---replay-to-number"></a>

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` <a href="#no-conn" id="no-conn"></a>

Disable the control pane unix socket.

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

### `--no-dock` <a href="#no-dock" id="no-dock"></a>

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

```sh
./urbit --no-dock -w sampel-palnet -k /path/to/my.key
```

### `-p, --ames-port PORT` <a href="#p---ames-port-port" id="p---ames-port-port"></a>

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` <a href="#p---profile" id="p---profile"></a>

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 [`~$`](https://docs.urbit.org/hoon/rune/sig#sigbuc) 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` <a href="#q---quiet" id="q---quiet"></a>

Run a ship without verbosity.

This disables the output that the [`|verb`](https://docs.urbit.org/os/dojo-tools#verb) command toggles. This is the opposite of [`-v`](#v---verbose). 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` <a href="#r---replay-from-number" id="r---replay-from-number"></a>

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`](#cram) or [`-n`](#n---replay-to-number).

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

### `-R, --versions` <a href="#r---versions" id="r---versions"></a>

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` <a href="#t---no-tty" id="t---no-tty"></a>

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` <a href="#u---bootstrap-url-url" id="u---bootstrap-url-url"></a>

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

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

### `--urth-loom SIZE` <a href="#urth-loom-size" id="urth-loom-size"></a>

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`](#--loom-size) 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` <a href="#v---verbose" id="v---verbose"></a>

Run a ship with verbose output. This is the same as what you get when you run [`|verb`](https://docs.urbit.org/os/dojo-tools#verb), and can be disabled by running `|verb`. This is the opposite of [`-q`](#q---quiet).

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

### `-w, --name NAME` <a href="#w---name-name" id="w---name-name"></a>

Boot a new ship with an Urbit ID of `NAME`.

The `NAME` is the ordinary [`@p`](https://docs.urbit.org/build-on-urbit/hoon-school/e-types#what-auras-are-there) 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.

```sh
./urbit -w sampel-palnet -k /path/to/my.key
```

### `-x, --exit` <a href="#x---exit" id="x---exit"></a>

Run a ship but exist immediately after it starts.

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

### `-X, --scry PATH` <a href="#x---scry-path" id="x---scry-path"></a>

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` <a href="#y---scry-info-file" id="y---scry-info-file"></a>

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` <a href="#z---scry-format-format" id="z---scry-format-format"></a>

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`