@@ -0,0 +1,632 @@
1++++
2+title = "Runtime Reference"
3+template = "doc.html"
4+weight = 0
5++++
6+
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).
10+
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.
15+
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.
21+
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)).
30+
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`.
36+
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.
43+
44+## Common Usage
45+
46+### Boot comet
47+
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
50+out Urbit.
51+
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):
54+
55+```
56+urbit -c some-pier-name
57+```
58+
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.
61+
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`.
64+
65+### Boot ship
66+
67+To boot a moon, planet, star or galaxy, you must use two arguments:
68+
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).
72+
73+```
74+urbit -w sampel-palnet -k /path/to/my.key
75+```
76+
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.
79+
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.
84+
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`.
87+
88+### Run ship
89+
90+If a ship has already been boostrapped, you can run it by simply specifying the
91+pier:
92+
93+```
94+urbit /path/to/pier
95+```
96+
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.
100+
101+### Boot fake ship
102+
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
106+machine.
107+
108+To create one, you just use the `-F` option and specify the name of a ship
109+(commonly a galaxy):
110+
111+```
112+urbit -F zod
113+```
114+
115+### Compact State
116+
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.
121+
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.
124+
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.
127+
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.
132+
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.
135+
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.
138+
139+**Note that the ships must not be running when using either of these.**
140+
141+### Dock binary
142+
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:
148+
149+```
150+urbit dock /path/to/pier
151+```
152+
153+Afterwards, you'll be able to just do `/path/to/pier/.run` and can delete the
154+separate `urbit` binary.
155+
156+### Update binary
157+
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.
162+
163+## Utilities
164+
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`.
169+
170+### `cram`
171+
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
174+snapshot backup.
175+
176+- Undocked: `urbit cram [pier]`
177+- Docked: `[pier]/.run cram`
178+
179+### `dock`
180+
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
187+`[pier]/.run`.
188+
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
191+command.
192+
193+- Undocked: `urbit dock [pier]`
194+- Docked: `[pier]/.run dock`
195+
196+Note the auto-dock behavior when booting new ships can be disabled with the
197+`--no-dock` option.
198+
199+### `grab`
200+
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.
203+
204+- Undocked: `urbit grab [pier]`
205+- Docked: `[pier]/.run grab`
206+
207+### `info`
208+
209+Print pier information.
210+
211+- Undocked: `urbit info [pier]`
212+- Docked: `[pier]/.run info`
213+
214+```
215+> urbit info zod
216+loom: mapped 2048MB
217+boot: protected loom
218+live: loaded: MB/268.173.312
219+boot: installed 351 jets
220+
221+urbit: zod at event 256133
222+ disk: live=&, event=256133
223+
224+lmdb info:
225+ map size: 1099511627776
226+ page size: 4096
227+ max pages: 268435456
228+ number of pages used: 1506786
229+ last transaction ID: 255733
230+ max readers: 126
231+ number of readers used: 0
232+ file size (page): 6171795456
233+ file size (stat): 6171795456
234+```
235+
236+### `meld`
237+
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`.
241+
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.
245+
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.
248+
249+- Undocked: `urbit meld [pier]`
250+- Docked: `[pier]/.run meld`
251+
252+### `pack`
253+
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.
256+
257+- Undocked: `urbit pack [pier]`
258+- Docked: `[pier]/.run pack`
259+
260+### `prep`
261+
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
265+up-to-date.
266+
267+- Undocked: `urbit prep [pier]`
268+- Docked: `[pier]/.run prep`
269+
270+### `next`
271+
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.
274+
275+- Undocked: `urbit next [pier]`
276+- Docked: `[pier]/.run next`
277+
278+### `queu AT-EVENT`
279+
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`.
283+
284+- Undocked: `urbit queu [pier] 10000`
285+- Docked: `[pier]/.run queu 10000`
286+
287+### `vere ARGS DIR`
288+
289+Download a binary. `DIR` is an output directory (it must already exist) and `ARGS` are:
290+
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`.
295+
296+Example usage:
297+
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 .`
300+
301+### `serf`
302+
303+Run as a 'serf' (as though it were the previously separate `urbit-worker`).
304+
305+- Undocked: `urbit serf <pier> <key> <flags> <cache-size> <at-event>`
306+
307+## Options
308+
309+Below are all the options/flags/arguments that can be given to the urbit
310+runtime.
311+
312+### `-a, --abort`
313+
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.
316+
317+### `-A, --arvo DIR`
318+
319+When booting a new ship, use directory `DIR` for the initial `%base` desk sync,
320+rather than the one in the pill.
321+
322+```
323+urbit -w sampel-palnet -k /path/to/my.key -A /path/to/arvo
324+```
325+
326+### `-b, --http-ip IP`
327+
328+Bind the HTTP server to IP address `IP`.
329+
330+- Undocked: `urbit -b 192.168.1.10 [pier]`
331+- Docked: `[pier]/.run -b 192.168.1.10`
332+
333+```
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))
337+```
338+
339+### `-B, --bootstrap PILL`
340+
341+When booting a new ship, use file `PILL` for the pill, rather than the default
342+one fetched from `https://bootstrap.urbit.org`.
343+
344+```
345+urbit -w sampel-palnet -k /path/to/my.key -B /path/to/the.pill
346+```
347+
348+### `-c, --pier PIER`
349+
350+When booting a ship, name its pier as `PIER` rather than the usual `@p`.
351+
352+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -c foobar`
353+
354+The pier folder will be named `foobar` as a result of the above command.
355+
356+### `-C, --memo-cache-limit LIMIT`
357+
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
360+number of entries.
361+
362+- Undocked: `urbit -C 50000 [pier]`
363+- Docked: `[pier]/.run -C 50000`
364+
365+### `-d, --daemon`
366+
367+Run the ship in daemon mode. The process will be detached from the terminal
368+(this implies `-t`).
369+
370+- Undocked: `urbit -d [pier]`
371+- Docked: `[pier]/.run -d`
372+
373+### `-D, --replay`
374+
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.
378+
379+### `-e, --ethereum URL`
380+
381+Use the Ethereum gateway at `URL` rather than the default.
382+
383+- Undocked: `urbit -e https://the.url [pier]`
384+- Docked: `[pier]/.run -e https://the.url`
385+
386+### `-F, --fake SHIP`
387+
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.
390+
391+```
392+urbit -F zod
393+```
394+
395+### `-g, --gc`
396+
397+Set GC flag, dumping garbage collector logs to stdout.
398+
399+- Undocked: `urbit -g [pier]`
400+- Docked: `[pier]/.run -g`
401+
402+### `-G --key-string STRING`
403+
404+Boot a new ship with private key `STRING`.The private key is `@uw` format. See
405+`-k` for an alternative.
406+
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`
408+
409+### `--http-port PORT`
410+
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.
413+
414+- Undocked: `urbit --https-port 8085 [pier]`
415+- Docked: `[pier]/.run --https-port 8085`
416+
417+### `--https-port PORT`
418+
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
424+the ship itself.
425+
426+Note this is for secure HTTPS only, see `--http-port` for insecure HTTP.
427+
428+- Undocked: `urbit --https-port 8443 [pier]`
429+- Docked: `[pier]/.run --https-port 8443`
430+
431+### `-I, --inject FILE`
432+
433+Inject the event stored in `FILE` jamfile.
434+
435+- Undocked: `urbit -I /path/to/file.jam [pier]`
436+- Docked: `[pier]/.run -I /path/to/file.jam`
437+
438+### `-j, --json-trace`
439+
440+Create JSON trace files in `[pier]/.urb/put/trace`.
441+
442+- Undocked: `urbit -j [pier]`
443+- Docked: `[pier]/.run urbit -j`
444+
445+### `-J, --ivory-pill PILL`
446+
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.
450+
451+- Undocked: `urbit -J /path/to/ivory.pill [pier]`
452+- Docked: `[pier]/.run -J /path/to/ivory.pill`
453+
454+### `-k, --key-file KEYS`
455+
456+Boot a new ship with the private key file `KEY`. See `-G` for an alternative.
457+
458+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
459+
460+### `-K, --kernel-stage STAGE`
461+
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.
464+
465+### `-l, --lite-boot`
466+
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.
469+
470+### `-L, --local`
471+
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
474+work as normal.
475+
476+- Undocked: `urbit -L [pier]`
477+- Docked: `[pier]/.run -L`
478+
479+### `-n, --replay-to NUMBER`
480+
481+Replay up to the specified event `NUMBER`.
482+
483+- Undocked: `urbit -n 10000 [pier]`
484+- Docked: `[pier]/.run -n 10000`
485+
486+A snapshot will be saved in a jamfile at `[pier]/.urb/roc/[NUMBER].jam`.
487+
488+### `--no-conn`
489+
490+Disable the control pane unix socket.
491+
492+- Undocked: `urbit --no-conn [pier]`
493+- Docked: `[pier]/.run --no-conn`
494+
495+### `--no-dock`
496+
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.
500+
501+- Undocked: `urbit --no-dock -w sampel-palnet -k /path/to/my.key`
502+
503+### `-p, --ames-port PORT`
504+
505+Set the Ames UDP port to `PORT`. This is the port used for inter-ship
506+communications.
507+
508+- Undocked: `urbit -p 33333 [pier]`
509+- Docked: `[pier]/.run -p 33333`
510+
511+### `-P, --profile`
512+
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.
517+
518+- Undocked `urbit -P [pier]`
519+- Docked `[pier]/.run -P`
520+
521+### `-q, --quiet`
522+
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
525+`|verb`.
526+
527+- Undocked: `urbit -q [pier]`
528+- Docked: `[pier]/.run -q`
529+
530+### `-r, --replay-from NUMBER`
531+
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
535+`cram` or `-n`.
536+
537+- Undocked: `urbit -r 10000 [pier]`
538+- Docked: `[pier]/.run -r 10000`
539+
540+### `-R, --versions`
541+
542+Report Vere build info.
543+
544+```
545+> urbit -R
546+urbit 1.9
547+gmp: 6.2.1
548+sigsegv: 2.14
549+openssl: OpenSSL 1.1.1n 15 Mar 2022
550+libuv: 1.43.0
551+libh2o: 0.13.6
552+lmdb: 0.9.29
553+curl: 7.81.0
554+```
555+
556+- Undocked: `urbit -R [pier]`
557+- Docked: `[pier]/.run -R`
558+
559+### `-S, --skip-battery-hashes`
560+
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.
563+
564+### `-t, --no-tty`
565+
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
569+it was run.
570+
571+- Undocked: `urbit -t [pier]`
572+- Docked: `[pier]/.run -t`
573+
574+### `-u, --bootstrap-url URL`
575+
576+Boot a new ship, using the pill fetched from `URL` rather than the default one.
577+
578+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -u http://example.com/the.pill`
579+
580+### `-v, --verbose`
581+
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`.
584+
585+- Undocked: `urbit -v [pier]`
586+- Docked: `[pier]/.run -v`
587+
588+### `-w, --name NAME`
589+
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
593+new ship.
594+
595+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
596+
597+### `-x, --exit`
598+
599+Run a ship but exist immediately after it starts.
600+
601+- Undocked: `urbit -x [pier]`
602+- Docked: `[pier]/.run -x`
603+
604+### `-X, --scry PATH`
605+
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`.
611+
612+- Undocked: `urbit -X /cx/base/gen/code/hoon [pier]`
613+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon`
614+
615+### `-Y, --scry-info FILE`
616+
617+Optional name for the file produced by a scry performed with `-X`, rather than the scry path.
618+
619+- Undocked: `urbit -X /cx/base/gen/code/hoon -Y foobar [pier]`
620+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Y foobar`
621+
622+### `-Z, --scry-format FORMAT`
623+
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
629+a cell.
630+
631+- Undocked: `urbit -X /cx/base/gen/code/hoon -Z ud [pier]`
632+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Z ud`