@@ -0,0 +1,632 @@
2+title = "Runtime Reference"
7+Note: This guide is about the CLI-based runtime executable. If you're running
8+the desktop client Port, see the [separate guide for
9+that](/using/running/port).
11+The Urbit runtime is named Vere. It's the binary executable you use to run your
12+ship (`urbit` on Linux and MacOS, `urbit.exe` on Windows). Vere manages your
13+ship's [pier](https://urbit.org/docs/glossary/pier), handles events, and runs
14+the Nock virtual machine that performs your ship's computations.
16+Before version 1.9, Vere was split into two separate binaries: `urbit` and
17+`urbit-worker` (also known as the King and the Serf). As of version 1.9, these
18+have been merged into a single `urbit` (or `urbit.exe`) binary, though under the
19+hood there's still two separate processes. The alternative King written in
20+Haskell, `urbit-king`, has also been deprecated, so there's now only one binary.
22+Version 1.9 has introduced a couple of new features. The first is the concept of
23+"docking". When a new ship is booted, Vere will automatically copy itself into
24+the pier, at `[pier]/.bin/[pace]/vere-v[version]-[architecture]`. It will also
25+create a link to this file at `[pier]/.run`. This means that after the initial
26+boot, the pier is self-contained and can be run with `[pier]/.run`, making the
27+separate binary unnecessary. For older ships that were booted by a previous
28+binary, v1.9 or later will not automatically perform this step, so it must be
29+done with the `dock` utility ([see below](#dock)).
31+The `pace` mentioned in the path above is a new feature, and repesents a release
32+channel. At the time of writing, the default `pace` is `live`, which is for
33+standard, stable releases. Alternative release channels will be introduced in
34+the future, for things such as pre-release testing, nightly builds, etc. The
35+`pace` is specified in a text file at `[pier]/.bin/pace`.
37+Along with docking, a binary upgrade feature has also been introduced. If you
38+run the `next` utility ([described below](#next)), Vere will check if there is a
39+newer binary version available for the current `pace`. if there is, it will
40+automatically be downloaded and installed. This means it's no longer necessary
41+to go and manually download new binaries and swap them out, it's all managed
42+inside the pier by Vere.
48+A comet is a kind of ship which may be quickly generated by anyone and which are
49+virtually unlimited. They're useful as free identities for people to quickly try
52+To boot a comet, you just need to use the `-c` argument and specify the name for
53+the pier (the pier is folder containing the ship's state and event log):
56+urbit -c some-pier-name
59+It will take a few minutes to bootstrap. Once complete, you'll be able to
60+interact with the Dojo prompt and access the web interface in a browser.
62+When you eventually shut down the ship, the binary will copy itself into the
63+pier, so in future you can run it by doing `/path/to/pier/.run`.
67+To boot a moon, planet, star or galaxy, you must use two arguments:
69+- `-w` - the name of the ship (without the leading `~`).
70+- `-k` - the path to the key file which you downloaded from Bridge (or got from
71+ the parent planet and pasted into a file in the case of a moon).
74+urbit -w sampel-palnet -k /path/to/my.key
77+It will take a few minutes to bootstrap. Once complete, you'll be able to
78+interact with the Dojo prompt and access the web interface in a browser.
80+If you want, you can use and additional `-c` option to specify a name for the
81+pier. Without `-c`, the pier will be named the same as your ship. Note it's
82+possible to use `-G` in lieu of `-k` and paste the private key directly in as an
83+argument. This might be more convenient in the case of a moon.
85+When you eventually shut down the ship, the binary will copy itself into the
86+pier, so in future you can run it by doing `/path/to/pier/.run`.
90+If a ship has already been boostrapped, you can run it by simply specifying the
97+Alternatively, if the pier was booted by version 1.9 or later of the binary, or
98+if you've previously run `dock` on the pier, you don't need a separate urbit
99+binary and can just do `/path/to/pier/.run` to start the ship.
103+Development is often done on a "fake" ship rather than a real one. A fake ship
104+has no connection to the real network, and uses fake keys so you don't actually
105+need to own it. A fake ship can only talk to other fake ships on the same local
108+To create one, you just use the `-F` option and specify the name of a ship
117+Ships currently have a hard 2GB limit on the size of their state. Sometimes the
118+state of long-running, heavily-used ships can exceed the 2GB limit and crash
119+with a `bail: meme` error. To fix this, there are a couple of ways to reduce the
120+size of the ship's state.
122+The first is the `pack` utility, which defragments the ship's snapshot. This
123+usually only mildly compacts the state, but it is fast and uses little memory.
125+To run `pack`, you can do either `urbit pack /path/to/pier` or
126+`/path/to/pier/.run pack` if it's been docked.
128+The second option is `meld`, which deduplicates the ship's snapshot. This can
129+reduce the size much more significantly, sometimes by as much as half. This can
130+use a lot of memory to complete, sometimes as much as 8GB, so if you don't have
131+ample memory on your machine you might need to map some swap space.
133+To run `meld`, you can either do `urbit meld /path/to/pier` or
134+`/path/to/pier/.run meld` if it's been docked.
136+If the meld succeeds, it'll print a memory report and exit. If it exits with
137+`KILLED`, it means it ran out of memory and the meld was aborted.
139+**Note that the ships must not be running when using either of these.**
143+From binary version 1.9 onwards, newly booted ships will have the binary
144+automatically copied into their piers, so they can be run by doing
145+`/path/to/pier/.run`. The means a separate binary is unnecessary, it's all
146+contained in the pier. For existing ships booted before v1.9, you need to
147+manually run the following command if you want this feature:
150+urbit dock /path/to/pier
153+Afterwards, you'll be able to just do `/path/to/pier/.run` and can delete the
154+separate `urbit` binary.
158+From binary version 1.9 onwards, there is a mechanism to update the binary
159+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
160+newer binaries are available for your release channel and if there are, it'll
161+automatically download the new one and install it in the pier.
165+These utilities are not used to run ships, but perform operations on piers,
166+print information about piers, or otherwise do useful things. Note the ship must
167+be stopped to run any of these utilities on a pier. Some of these are utilities
168+of the previously separate `urbit-worker`.
172+Jam the state of a ship. The jamfile will be saved in
173+`[pier]/.urb/roc/[current-event-number].jam`. This creates a portable
176+- Undocked: `urbit cram [pier]`
177+- Docked: `[pier]/.run cram`
181+Copies the urbit binary into the target pier. The binary itself will be copied
182+to `[pier]/.bin/[pace]/vere-v[version]-[architecture]`. The `pace` is a
183+release channel. The default `pace` is `live`, for ordinary stable releases. The
184+pace will also be recorded in a text file at `[pier]/.bin/pace`.
185+Additionally, a link to the current binary will be created at
186+`[pier]/.run`, which allows you to start a ship by calling
189+When a ship is newly booted by a runtime from `v1.9` onwards, it will be
190+automatically docked. For existing ships, it must be done explicitly with this
193+- Undocked: `urbit dock [pier]`
194+- Docked: `[pier]/.run dock`
196+Note the auto-dock behavior when booting new ships can be disabled with the
201+Measure memory usage analysis of a ship. The result will be printed to the
202+terminal. This is the same output produced by running `|mass` in the Dojo.
204+- Undocked: `urbit grab [pier]`
205+- Docked: `[pier]/.run grab`
209+Print pier information.
211+- Undocked: `urbit info [pier]`
212+- Docked: `[pier]/.run info`
218+live: loaded: MB/268.173.312
219+boot: installed 351 jets
221+urbit: zod at event 256133
222+ disk: live=&, event=256133
225+ map size: 1099511627776
227+ max pages: 268435456
228+ number of pages used: 1506786
229+ last transaction ID: 255733
231+ number of readers used: 0
232+ file size (page): 6171795456
233+ file size (stat): 6171795456
238+Deduplicate ship state. This can significantly reduce memory usage for ships
239+with large states. This is a common solution when ships use up all available
240+mapped memory (currently 2GB) and crash with `bail: meme`.
242+Note this command may use a large amount of memory during execution, up to
243+around 8GB or so, depending on the size of the ship's state and other factors.
244+If you do not have enough memory to run it, you may need to allocate some swap.
246+If the meld succeeds, it will print out a memory usage report. If it exits
247+saying `KILLED`, it means it ran out of memory and the operation was aborted.
249+- Undocked: `urbit meld [pier]`
250+- Docked: `[pier]/.run meld`
254+Defragment a ship's state. This will reduce the size of a ship's state much less
255+than `meld`, but it is much faster and requires much less memory to complete.
257+- Undocked: `urbit pack [pier]`
258+- Docked: `[pier]/.run pack`
262+Prepare a pier for upgrade. This utility is designed to be a general-purpose
263+forward-compatibility mechanism. What action (if any) is taken depends on the
264+old version and new version. Currently, it just makes sure the snapshot is fully
267+- Undocked: `urbit prep [pier]`
268+- Docked: `[pier]/.run prep`
272+Request a runtime upgrade. If your binary is already the latest version, no
273+action will be taken. If a new binary is available, it will be upgraded.
275+- Undocked: `urbit next [pier]`
276+- Docked: `[pier]/.run next`
280+Load a snapshot jamfile. `AT-EVENT` is an event number. There must be
281+corresponding snapshot in `[pier]/.urb/roc/[AT-EVENT].jam` created
282+previously with `cram` or `-n`.
284+- Undocked: `urbit queu [pier] 10000`
285+- Docked: `[pier]/.run queu 10000`
289+Download a binary. `DIR` is an output directory (it must already exist) and `ARGS` are:
291+- `-a, --arch ARCH` - architecture, `ARCH` may be one of `x86_64-linux`,
292+ `x86_64-darwin`, and `x86_64-windows`, though more may be added in the future.
293+- `-v, --version VER` - version number, `VER` is e.g. `1.9`.
294+- `-p, --pace` - release channel, e.g. `live`.
298+- Undocked: `urbit vere -a x86_64-linux -v 1.9 -p live .`
299+- Docked: `[pier]/.run vere -a x86_64-linux -v 1.9 -p live .`
303+Run as a 'serf' (as though it were the previously separate `urbit-worker`).
305+- Undocked: `urbit serf <pier> <key> <flags> <cache-size> <at-event>`
309+Below are all the options/flags/arguments that can be given to the urbit
314+Abort aggressively. This option is currently a no-op, and doesn't do anything.
315+It may be revived in the future or it may be removed.
319+When booting a new ship, use directory `DIR` for the initial `%base` desk sync,
320+rather than the one in the pill.
323+urbit -w sampel-palnet -k /path/to/my.key -A /path/to/arvo
326+### `-b, --http-ip IP`
328+Bind the HTTP server to IP address `IP`.
330+- Undocked: `urbit -b 192.168.1.10 [pier]`
331+- Docked: `[pier]/.run -b 192.168.1.10`
334+> ss -tlnp | grep urbit
335+LISTEN 0 16 127.0.0.1:12321 0.0.0.0:* users:(("urbit",pid=15689,fd=29))
336+LISTEN 0 16 192.168.1.10:8080 0.0.0.0:* users:(("urbit",pid=15689,fd=28))
339+### `-B, --bootstrap PILL`
341+When booting a new ship, use file `PILL` for the pill, rather than the default
342+one fetched from `https://bootstrap.urbit.org`.
345+urbit -w sampel-palnet -k /path/to/my.key -B /path/to/the.pill
348+### `-c, --pier PIER`
350+When booting a ship, name its pier as `PIER` rather than the usual `@p`.
352+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -c foobar`
354+The pier folder will be named `foobar` as a result of the above command.
356+### `-C, --memo-cache-limit LIMIT`
358+This sets the maximum number of entries for the memoization cache (used by the
359+`~+` rune and a few other things). Zero means uncapped, otherwise the specified
362+- Undocked: `urbit -C 50000 [pier]`
363+- Docked: `[pier]/.run -C 50000`
367+Run the ship in daemon mode. The process will be detached from the terminal
370+- Undocked: `urbit -d [pier]`
371+- Docked: `[pier]/.run -d`
375+Recompute a ship's state from events rather than loading its checkpoint. This
376+option is currently a no-op, and doesn't do anything. It may be revived in the
377+future or it may be removed.
379+### `-e, --ethereum URL`
381+Use the Ethereum gateway at `URL` rather than the default.
383+- Undocked: `urbit -e https://the.url [pier]`
384+- Docked: `[pier]/.run -e https://the.url`
386+### `-F, --fake SHIP`
388+Boot a new fake development ship. Real networking is disabled, and instead the
389+fake ship can only communicate with other fake ships on the local machine.
397+Set GC flag, dumping garbage collector logs to stdout.
399+- Undocked: `urbit -g [pier]`
400+- Docked: `[pier]/.run -g`
402+### `-G --key-string STRING`
404+Boot a new ship with private key `STRING`.The private key is `@uw` format. See
405+`-k` for an alternative.
407+- 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`
409+### `--http-port PORT`
411+Set the HTTP port to `PORT`. This is the port you'd insecurely access Landscape
412+on. Note this is for insecure HTTP only, see `--https-port` for HTTPS.
414+- Undocked: `urbit --https-port 8085 [pier]`
415+- Docked: `[pier]/.run --https-port 8085`
417+### `--https-port PORT`
419+Set the HTTPS port to `PORT`. This is the port you'd securely access Landscape
420+on. Note that this requires an SSL certificate to be configured, see the
421+[Configuring SSL guide](https://urbit.org/using/os/basics#configuring-ssl) for
422+details. Note that if your ship is behind a reverse proxy (nginx, Caddy, etc)
423+and an SSL certificate is configured _there_, you'd not usually enable HTTPS on
426+Note this is for secure HTTPS only, see `--http-port` for insecure HTTP.
428+- Undocked: `urbit --https-port 8443 [pier]`
429+- Docked: `[pier]/.run --https-port 8443`
431+### `-I, --inject FILE`
433+Inject the event stored in `FILE` jamfile.
435+- Undocked: `urbit -I /path/to/file.jam [pier]`
436+- Docked: `[pier]/.run -I /path/to/file.jam`
438+### `-j, --json-trace`
440+Create JSON trace files in `[pier]/.urb/put/trace`.
442+- Undocked: `urbit -j [pier]`
443+- Docked: `[pier]/.run urbit -j`
445+### `-J, --ivory-pill PILL`
447+This specifies an alternative Ivory pill to use. An Ivory pill is a pill
448+compiled into the binary and used for runtime support code. You would not
449+typically use this unless you're doing runtime or kernel development.
451+- Undocked: `urbit -J /path/to/ivory.pill [pier]`
452+- Docked: `[pier]/.run -J /path/to/ivory.pill`
454+### `-k, --key-file KEYS`
456+Boot a new ship with the private key file `KEY`. See `-G` for an alternative.
458+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
460+### `-K, --kernel-stage STAGE`
462+Start at Hoon kernel version stage specified. This option is currently a no-op,
463+and doesn't do anything. It may be revived in the future or it may be removed.
465+### `-l, --lite-boot`
467+Most-minimal startup. This option is currently a no-op, and doesn't do anything.
468+It may be revived in the future or it may be removed.
472+Run a ship with local networking only. This will disable Ames networking, so the
473+ship will not be able to communicate with other ships. HTTP(S) will continue to
476+- Undocked: `urbit -L [pier]`
477+- Docked: `[pier]/.run -L`
479+### `-n, --replay-to NUMBER`
481+Replay up to the specified event `NUMBER`.
483+- Undocked: `urbit -n 10000 [pier]`
484+- Docked: `[pier]/.run -n 10000`
486+A snapshot will be saved in a jamfile at `[pier]/.urb/roc/[NUMBER].jam`.
490+Disable the control pane unix socket.
492+- Undocked: `urbit --no-conn [pier]`
493+- Docked: `[pier]/.run --no-conn`
497+From v1.8 onwards, when a new ship is booted, the urbit binary will copy itself
498+into the newly created pier by default (see the [`dock`](#dock) section for
499+details). To prevent this from happening, the `--no-dock` option can be used.
501+- Undocked: `urbit --no-dock -w sampel-palnet -k /path/to/my.key`
503+### `-p, --ames-port PORT`
505+Set the Ames UDP port to `PORT`. This is the port used for inter-ship
508+- Undocked: `urbit -p 33333 [pier]`
509+- Docked: `[pier]/.run -p 33333`
513+Enable profiling. Profiles will be saved to
514+`[pier]/.urb/put/profile/[now].txt`. This is useful for debugging and
515+development. Profiling hit counters in Hoon code specified with the `~$` rune
516+will be recorded here.
518+- Undocked `urbit -P [pier]`
519+- Docked `[pier]/.run -P`
523+Run a ship without verbosity. This disables the output that the `|verb` command
524+toggles. This is the opposite of `-v`. Verbosity can be enabled again by running
527+- Undocked: `urbit -q [pier]`
528+- Docked: `[pier]/.run -q`
530+### `-r, --replay-from NUMBER`
532+Load snapshot at event `NUMBER`, only replay after that event. This lets you
533+resume a partially completed replay. For the given `NUMBER`, there must be
534+a corresponding snapshot in `[pier]/.urb/roc/[NUMBER].jam`, created by
537+- Undocked: `urbit -r 10000 [pier]`
538+- Docked: `[pier]/.run -r 10000`
542+Report Vere build info.
549+openssl: OpenSSL 1.1.1n 15 Mar 2022
556+- Undocked: `urbit -R [pier]`
557+- Docked: `[pier]/.run -R`
559+### `-S, --skip-battery-hashes`
561+Disable battery hashing. This option is currently a no-op, and doesn't do
562+anything. It may be revived in the future or it may be removed.
566+Disable terminal/TTY assumptions. With this set, there will be no Dojo prompt,
567+and you'll only see debug messages from the runtime. This is similar to daemon
568+mode (see `-d`), but the process will remain attached to the terminal in which
571+- Undocked: `urbit -t [pier]`
572+- Docked: `[pier]/.run -t`
574+### `-u, --bootstrap-url URL`
576+Boot a new ship, using the pill fetched from `URL` rather than the default one.
578+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -u http://example.com/the.pill`
582+Run a ship with verbose output. This is the same as what you get when you run
583+`|verb`, and can be disabled by running `|verb`. This is the opposite of `-q`.
585+- Undocked: `urbit -v [pier]`
586+- Docked: `[pier]/.run -v`
588+### `-w, --name NAME`
590+Boot a new ship with an Urbit ID of `NAME`. The `NAME` is the ordinary `@p`
591+format but without the leading `~`, so `~sampel-palnet` is specified as
592+`sampel-palnet`. This is typically used in conjunction with `-k` when booting a
595+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
599+Run a ship but exist immediately after it starts.
601+- Undocked: `urbit -x [pier]`
602+- Docked: `[pier]/.run -x`
604+### `-X, --scry PATH`
606+Read a ship's state on scry path `PATH`, jamming the result and saving it to
607+`[pier]/.urb/put/[PATH].jam`. The scry path is in the format
608+`/[care]/[path]`, omitting the ship and case elements. For example,
609+`/cx/~zod/base/~2022.6.2..11.27.40..8f56/gen/code/hoon` would be
610+`/cx/base/gen/code/hoon`.
612+- Undocked: `urbit -X /cx/base/gen/code/hoon [pier]`
613+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon`
615+### `-Y, --scry-info FILE`
617+Optional name for the file produced by a scry performed with `-X`, rather than the scry path.
619+- Undocked: `urbit -X /cx/base/gen/code/hoon -Y foobar [pier]`
620+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Y foobar`
622+### `-Z, --scry-format FORMAT`
624+Optionally specify the output format for the file produced by a `-X` scry. The
625+format may either be `jam` to produce a jam file, or else an aura. If it's an
626+aura, the leading `@` is omitted, so `@ud` is specified as `ud`. If an aura is
627+specified, the resulting atom is encoded in a text file with that aura's
628+formatting. If an aura is specified, the scry endpoint must produce an atom, not
631+- Undocked: `urbit -X /cx/base/gen/code/hoon -Z ud [pier]`
632+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Z ud`