@@ -0,0 +1,623 @@
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: The `urbit`
17+"king" responsible for I/O and event persistence, and the `urbit-worker` "serf"
18+responsible for computations and state persistence. As of version 1.9, these
19+have been merged into a single `urbit` (or `urbit.exe`) binary, though under the
20+hood there's still two separate processes. The alternative king written in
21+Haskell, `urbit-king`, has also been deprecated, so there's now only one binary.
22+
23+Version 1.9 has introduced a couple of new features. The first is the concept of
24+"docking". When a new ship is booted, Vere will automatically copy itself into
25+the pier, at `[pier]/.bin/[pace]/vere-v[version]-[architecture]`. It will also
26+create a link to this file at `[pier]/.run`. This means that after the initial
27+boot, the pier is self-contained and can be run with `[pier]/.run`, making the
28+separate binary unnecessary. For older ships that were booted by a previous
29+binary, v1.9 or later will not automatically perform this step, so it must be
30+done with the `dock` utility ([see below](#dock)).
31+
32+The `pace` mentioned in the path above is a new feature, and represents a
33+release channel. At the time of writing, the default `pace` is `live`, which is
34+for standard, stable releases. Alternative release channels will be introduced
35+in the future, for things such as pre-release testing, nightly builds, etc. The
36+`pace` is specified in a text file at `[pier]/.bin/pace`.
37+
38+Along with docking, a binary upgrade feature has also been introduced. If you
39+run the `next` utility ([described below](#next)), Vere will check if there is a
40+newer binary version available for the current `pace`. if there is, it will
41+automatically be downloaded and installed. This means it's no longer necessary
42+to go and manually download new binaries and swap them out, it's all managed
43+inside the pier by Vere.
44+
45+## Common Usage
46+
47+### Boot comet
48+
49+A comet is a kind of ship which may be quickly generated by anyone and which are
50+virtually unlimited. They're useful as free identities for people to quickly try
51+out Urbit.
52+
53+To boot a comet, you just need to use the `-c` argument and specify the name for
54+the pier (the pier is folder containing the ship's state and event log):
55+
56+```
57+urbit -c some-pier-name
58+```
59+
60+It will take a few minutes to bootstrap. Once complete, you'll be able to
61+interact with the Dojo prompt and access the web interface in a browser.
62+
63+When you eventually shut down the ship, the binary will copy itself into the
64+pier, so in future you can run it by doing `/path/to/pier/.run`.
65+
66+### Boot ship
67+
68+To boot a moon, planet, star or galaxy, you must use two arguments:
69+
70+- `-w` - the name of the ship (without the leading `~`).
71+- `-k` - the path to the key file which you downloaded from Bridge (or got from
72+ the parent planet and pasted into a file in the case of a moon).
73+
74+```
75+urbit -w sampel-palnet -k /path/to/my.key
76+```
77+
78+It will take a few minutes to bootstrap. Once complete, you'll be able to
79+interact with the Dojo prompt and access the web interface in a browser.
80+
81+If you want, you can use and additional `-c` option to specify a name for the
82+pier. Without `-c`, the pier will be named the same as your ship. Note it's
83+possible to use `-G` in lieu of `-k` and paste the private key directly in as an
84+argument. This might be more convenient in the case of a moon.
85+
86+When you eventually shut down the ship, the binary will copy itself into the
87+pier, so in future you can run it by doing `/path/to/pier/.run`.
88+
89+### Run ship
90+
91+If a ship has already been boostrapped, you can run it by simply specifying the
92+pier:
93+
94+```
95+urbit /path/to/pier
96+```
97+
98+Alternatively, if the pier was booted by version 1.9 or later of the binary, or
99+if you've previously run `dock` on the pier, you don't need a separate urbit
100+binary and can just do `/path/to/pier/.run` to start the ship.
101+
102+### Boot fake ship
103+
104+Development is often done on a "fake" ship rather than a real one. A fake ship
105+has no connection to the real network, and uses fake keys so you don't actually
106+need to own it. A fake ship can only talk to other fake ships on the same local
107+machine.
108+
109+To create one, you just use the `-F` option and specify the name of a ship
110+(commonly a galaxy):
111+
112+```
113+urbit -F zod
114+```
115+
116+### Compact State
117+
118+**Note the ship should be shut down before using either of the utilities described below.**
119+
120+Ships currently have a hard 2GB limit on the size of their state. Sometimes the
121+state of long-running, heavily-used ships can exceed the 2GB limit and crash
122+with a `bail: meme` error. To fix this, there are a couple of ways to reduce the
123+size of the ship's state.
124+
125+The first is the `pack` utility, which defragments the ship's snapshot. This
126+usually only mildly compacts the state, but it is fast and uses little memory.
127+
128+To run `pack`, you can do either `urbit pack /path/to/pier` or
129+`/path/to/pier/.run pack` if it's been docked.
130+
131+The second option is `meld`, which deduplicates the ship's snapshot. This can
132+reduce the size much more significantly, sometimes by as much as half. This can
133+use a lot of memory to complete, sometimes as much as 8GB, so if you don't have
134+ample memory on your machine you might need to map some swap space.
135+
136+To run `meld`, you can either do `urbit meld /path/to/pier` or
137+`/path/to/pier/.run meld` if it's been docked.
138+
139+If the meld succeeds, it'll print a memory report and exit. If it exits with
140+`KILLED`, it means it ran out of memory and the meld was aborted.
141+
142+### Dock binary
143+
144+From binary version 1.9 onwards, newly booted ships will have the binary
145+automatically copied into their piers, so they can be run by doing
146+`/path/to/pier/.run`. The means a separate binary is unnecessary, it's all
147+contained in the pier. For existing ships booted before v1.9, you need to
148+manually run the following command if you want this feature:
149+
150+```
151+urbit dock /path/to/pier
152+```
153+
154+Afterwards, you'll be able to just do `/path/to/pier/.run` and can delete the
155+separate `urbit` binary.
156+
157+### Update binary
158+
159+From binary version 1.9 onwards, there is a mechanism to update the binary
160+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
161+newer binaries are available for your release channel and if there are, it'll
162+automatically download the new one and install it in the pier.
163+
164+## Utilities
165+
166+These utilities are not used to run ships, but perform operations on piers,
167+print information about piers, or otherwise do useful things. Note the ship must
168+be stopped to run any of these utilities on a pier. Some of these are utilities
169+of the previously separate `urbit-worker`.
170+
171+### `cram`
172+
173+Jam the state of a ship. The jamfile will be saved in
174+`[pier]/.urb/roc/[current-event-number].jam`. This creates a portable
175+snapshot backup.
176+
177+- Undocked: `urbit cram [pier]`
178+- Docked: `[pier]/.run cram`
179+
180+### `dock`
181+
182+Copies the urbit binary into the target pier. The binary itself will be copied
183+to `[pier]/.bin/[pace]/vere-v[version]-[architecture]`. The `pace` is a
184+release channel. The default `pace` is `live`, for ordinary stable releases. The
185+pace will also be recorded in a text file at `[pier]/.bin/pace`.
186+Additionally, a link to the current binary will be created at
187+`[pier]/.run`, which allows you to start a ship by calling
188+`[pier]/.run`.
189+
190+When a ship is newly booted by a runtime from `v1.9` onwards, it will be
191+automatically docked. For existing ships, it must be done explicitly with this
192+command.
193+
194+- Undocked: `urbit dock [pier]`
195+- Docked: `[pier]/.run dock`
196+
197+Note the auto-dock behavior when booting new ships can be disabled with the
198+`--no-dock` option.
199+
200+### `grab`
201+
202+Measure memory usage analysis of a ship. The result will be printed to the
203+terminal. This is the same output produced by running `|mass` in the Dojo.
204+
205+- Undocked: `urbit grab [pier]`
206+- Docked: `[pier]/.run grab`
207+
208+### `info`
209+
210+Print pier information.
211+
212+- Undocked: `urbit info [pier]`
213+- Docked: `[pier]/.run info`
214+
215+```
216+> urbit info zod
217+loom: mapped 2048MB
218+boot: protected loom
219+live: loaded: MB/268.173.312
220+boot: installed 351 jets
221+
222+urbit: zod at event 256133
223+ disk: live=&, event=256133
224+
225+lmdb info:
226+ map size: 1099511627776
227+ page size: 4096
228+ max pages: 268435456
229+ number of pages used: 1506786
230+ last transaction ID: 255733
231+ max readers: 126
232+ number of readers used: 0
233+ file size (page): 6171795456
234+ file size (stat): 6171795456
235+```
236+
237+### `meld`
238+
239+Deduplicate ship state. This can significantly reduce memory usage for ships
240+with large states. This is a common solution when ships use up all available
241+mapped memory (currently 2GB) and crash with `bail: meme`.
242+
243+Note this command may use a large amount of memory during execution, up to
244+around 8GB or so, depending on the size of the ship's state and other factors.
245+If you do not have enough memory to run it, you may need to allocate some swap.
246+
247+If the meld succeeds, it will print out a memory usage report. If it exits
248+saying `KILLED`, it means it ran out of memory and the operation was aborted.
249+
250+- Undocked: `urbit meld [pier]`
251+- Docked: `[pier]/.run meld`
252+
253+### `pack`
254+
255+Defragment a ship's state. This will reduce the size of a ship's state much less
256+than `meld`, but it is much faster and requires much less memory to complete.
257+
258+- Undocked: `urbit pack [pier]`
259+- Docked: `[pier]/.run pack`
260+
261+### `prep`
262+
263+Prepare a pier for upgrade. This utility is designed to be a general-purpose
264+forward-compatibility mechanism. What action (if any) is taken depends on the
265+old version and new version. Currently, it just makes sure the snapshot is fully
266+up-to-date.
267+
268+- Undocked: `urbit prep [pier]`
269+- Docked: `[pier]/.run prep`
270+
271+### `next`
272+
273+Request a runtime upgrade. If your binary is already the latest version, no
274+action will be taken. If a new binary is available, it will be upgraded.
275+
276+- Undocked: `urbit next [pier]`
277+- Docked: `[pier]/.run next`
278+
279+### `queu AT-EVENT`
280+
281+Load a snapshot jamfile. `AT-EVENT` is an event number. There must be
282+corresponding snapshot in `[pier]/.urb/roc/[AT-EVENT].jam` created
283+previously with `cram` or `-n`.
284+
285+- Undocked: `urbit queu [pier] 10000`
286+- Docked: `[pier]/.run queu 10000`
287+
288+### `vere ARGS DIR`
289+
290+Download a binary. `DIR` is an output directory (it must already exist) and `ARGS` are:
291+
292+- `-a, --arch ARCH` - architecture, `ARCH` may be one of `x86_64-linux`,
293+ `x86_64-darwin`, and `x86_64-windows`, though more may be added in the future.
294+- `-v, --version VER` - version number, `VER` is e.g. `1.9`.
295+- `-p, --pace` - release channel, e.g. `live`.
296+
297+Example usage:
298+
299+- Undocked: `urbit vere -a x86_64-linux -v 1.9 -p live .`
300+
301+### `serf ARGS`
302+
303+Run as a 'serf' (as though it were the previously separate `urbit-worker`).
304+
305+Note this utility is for kernel development purposes and has a programmatic
306+interface, it does not have a user interface.
307+
308+- Undocked: `urbit serf [pier] [key] [flags] [cache-size] [at-event]`
309+
310+## Options
311+
312+Below are all the options/flags/arguments that can be given to the urbit
313+runtime.
314+
315+### `-A, --arvo DIR`
316+
317+When booting a new ship, use directory `DIR` for the initial `%base` desk sync,
318+rather than the one in the pill.
319+
320+```
321+urbit -w sampel-palnet -k /path/to/my.key -A /path/to/arvo
322+```
323+
324+### `-b, --http-ip IP`
325+
326+Bind the HTTP server to IP address `IP`.
327+
328+- Undocked: `urbit -b 192.168.1.10 [pier]`
329+- Docked: `[pier]/.run -b 192.168.1.10`
330+
331+```
332+> ss -tlnp | grep urbit
333+LISTEN 0 16 127.0.0.1:12321 0.0.0.0:* users:(("urbit",pid=15689,fd=29))
334+LISTEN 0 16 192.168.1.10:8080 0.0.0.0:* users:(("urbit",pid=15689,fd=28))
335+```
336+
337+### `-B, --bootstrap PILL`
338+
339+When booting a new ship, use file `PILL` for the pill, rather than the default
340+one fetched from `https://bootstrap.urbit.org`.
341+
342+```
343+urbit -w sampel-palnet -k /path/to/my.key -B /path/to/the.pill
344+```
345+
346+### `-c, --pier PIER`
347+
348+When booting a ship, name its pier as `PIER` rather than the usual `@p`.
349+
350+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -c foobar`
351+
352+The pier folder will be named `foobar` as a result of the above command.
353+
354+### `-C, --memo-cache-limit LIMIT`
355+
356+This sets the maximum number of entries for the memoization cache (used by the
357+`~+` rune and a few other things). Zero means uncapped, otherwise the specified
358+number of entries.
359+
360+- Undocked: `urbit -C 50000 [pier]`
361+- Docked: `[pier]/.run -C 50000`
362+
363+### `-d, --daemon`
364+
365+Run the ship in daemon mode. The process will be detached from the terminal
366+(this implies `-t`).
367+
368+- Undocked: `urbit -d [pier]`
369+- Docked: `[pier]/.run -d`
370+
371+### `-e, --ethereum URL`
372+
373+Use the Ethereum gateway at `URL` rather than the default.
374+
375+- Undocked: `urbit -e https://the.url [pier]`
376+- Docked: `[pier]/.run -e https://the.url`
377+
378+### `-F, --fake SHIP`
379+
380+Boot a new fake development ship. Real networking is disabled, and instead the
381+fake ship can only communicate with other fake ships on the local machine. This
382+works for all ship classes except comets.
383+
384+```
385+urbit -F zod
386+```
387+
388+### `-g, --gc`
389+
390+Set GC flag, dumping garbage collector logs to stdout. This runs a GC pass at
391+the end of every virtualized computation. This is intended as a runtime
392+developer/QA tool for verifying refcounts. This currently only works if the
393+binary was built with `MEMORY_DEBUG` (which changes allocation structures and
394+produces incompatible snapshots).
395+
396+- Undocked: `urbit -g [pier]`
397+- Docked: `[pier]/.run -g`
398+
399+### `-G --key-string STRING`
400+
401+Boot a new ship with private key `STRING`.The private key is `@uw` format. See
402+`-k` for an alternative.
403+
404+- 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`
405+
406+### `--http-port PORT`
407+
408+Set the HTTP port to `PORT`. This is the port you'd insecurely access Landscape
409+on. Note this is for insecure HTTP only, see `--https-port` for HTTPS.
410+
411+- Undocked: `urbit --http-port 8085 [pier]`
412+- Docked: `[pier]/.run --http-port 8085`
413+
414+### `--https-port PORT`
415+
416+Set the HTTPS port to `PORT`. This is the port you'd securely access Landscape
417+on. Note that this requires an SSL certificate to be configured, see the
418+[Configuring SSL guide](https://urbit.org/using/os/basics#configuring-ssl) for
419+details. Note that if your ship is behind a reverse proxy (nginx, Caddy, etc)
420+and an SSL certificate is configured _there_, you'd not usually enable HTTPS on
421+the ship itself.
422+
423+Note this is for secure HTTPS only, see `--http-port` for insecure HTTP.
424+
425+- Undocked: `urbit --https-port 8443 [pier]`
426+- Docked: `[pier]/.run --https-port 8443`
427+
428+### `-I, --inject FILE`
429+
430+Inject the event stored in `FILE` jamfile.
431+
432+Note this has "full privileges" and can do anything to your ship. `-I` is for
433+customization in hosting environments, and emergency recovery for sinking ships.
434+Only run from trusted sources.
435+
436+- Undocked: `urbit -I /path/to/file.jam [pier]`
437+- Docked: `[pier]/.run -I /path/to/file.jam`
438+
439+### `-j, --json-trace`
440+
441+Create JSON trace files in `[pier]/.urb/put/trace`.
442+
443+This runs a tracing profiler, and produces JSON output compatible with
444+`chrome://tracing`.
445+
446+- Undocked: `urbit -j [pier]`
447+- Docked: `[pier]/.run urbit -j`
448+
449+### `-J, --ivory-pill PILL`
450+
451+This specifies an alternative Ivory pill to use. An Ivory pill is a pill
452+compiled into the binary and used for runtime support code. You would not
453+typically use this unless you're doing runtime or kernel development.
454+
455+- Undocked: `urbit -J /path/to/ivory.pill [pier]`
456+- Docked: `[pier]/.run -J /path/to/ivory.pill`
457+
458+### `-k, --key-file KEYS`
459+
460+Boot a new ship with the private key file `KEY`. See `-G` for an alternative.
461+
462+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
463+
464+### `-L, --local`
465+
466+Run a ship with local networking only. This will disable Ames networking, so the
467+ship will not be able to communicate with other ships. HTTP(S) will continue to
468+work as normal.
469+
470+- Undocked: `urbit -L [pier]`
471+- Docked: `[pier]/.run -L`
472+
473+### `-n, --replay-to NUMBER`
474+
475+Replay up to the specified event `NUMBER`.
476+
477+- Undocked: `urbit -n 10000 [pier]`
478+- Docked: `[pier]/.run -n 10000`
479+
480+A snapshot will be saved in a jamfile at `[pier]/.urb/roc/[NUMBER].jam`.
481+
482+### `--no-conn`
483+
484+Disable the control pane unix socket.
485+
486+- Undocked: `urbit --no-conn [pier]`
487+- Docked: `[pier]/.run --no-conn`
488+
489+### `--no-dock`
490+
491+From v1.9 onwards, when a new ship is booted, the urbit binary will copy itself
492+into the newly created pier by default (see the [`dock`](#dock) section for
493+details). To prevent this from happening, the `--no-dock` option can be used.
494+
495+- Undocked: `urbit --no-dock -w sampel-palnet -k /path/to/my.key`
496+
497+### `-p, --ames-port PORT`
498+
499+Set the Ames UDP port to `PORT`. This is the port used for inter-ship
500+communications.
501+
502+- Undocked: `urbit -p 33333 [pier]`
503+- Docked: `[pier]/.run -p 33333`
504+
505+### `-P, --profile`
506+
507+Enable profiling. Profiles will be saved to `[pier]/.urb/put/profile/[now].txt`.
508+This is useful for debugging and development. Profiling hit counters in Hoon
509+code specified with the `~$` rune will be recorded here.
510+
511+This runs a sampling profiler and produces custom output. Runtime cost metrics
512+are only calculated if the binary was built with `CPU_DEBUG`.
513+
514+- Undocked `urbit -P [pier]`
515+- Docked `[pier]/.run -P`
516+
517+### `-q, --quiet`
518+
519+Run a ship without verbosity. This disables the output that the `|verb` command
520+toggles. This is the opposite of `-v`. Verbosity can be enabled again by running
521+`|verb`.
522+
523+- Undocked: `urbit -q [pier]`
524+- Docked: `[pier]/.run -q`
525+
526+### `-r, --replay-from NUMBER`
527+
528+Load snapshot at event `NUMBER`, only replay after that event. This lets you
529+resume a partially completed replay. For the given `NUMBER`, there must be
530+a corresponding snapshot in `[pier]/.urb/roc/[NUMBER].jam`, created by
531+`cram` or `-n`.
532+
533+- Undocked: `urbit -r 10000 [pier]`
534+- Docked: `[pier]/.run -r 10000`
535+
536+### `-R, --versions`
537+
538+Report Vere build info.
539+
540+```
541+> urbit -R
542+urbit 1.9
543+gmp: 6.2.1
544+sigsegv: 2.14
545+openssl: OpenSSL 1.1.1n 15 Mar 2022
546+libuv: 1.43.0
547+libh2o: 0.13.6
548+lmdb: 0.9.29
549+curl: 7.81.0
550+```
551+
552+- Undocked: `urbit -R [pier]`
553+- Docked: `[pier]/.run -R`
554+
555+### `-t, --no-tty`
556+
557+Disable terminal/TTY assumptions. With this set, there will be no Dojo prompt,
558+and you'll only see debug messages from the runtime. This is similar to daemon
559+mode (see `-d`), but the process will remain attached to the terminal in which
560+it was run.
561+
562+- Undocked: `urbit -t [pier]`
563+- Docked: `[pier]/.run -t`
564+
565+### `-u, --bootstrap-url URL`
566+
567+Boot a new ship, using the pill fetched from `URL` rather than the default one.
568+
569+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -u http://example.com/the.pill`
570+
571+### `-v, --verbose`
572+
573+Run a ship with verbose output. This is the same as what you get when you run
574+`|verb`, and can be disabled by running `|verb`. This is the opposite of `-q`.
575+
576+- Undocked: `urbit -v [pier]`
577+- Docked: `[pier]/.run -v`
578+
579+### `-w, --name NAME`
580+
581+Boot a new ship with an Urbit ID of `NAME`. The `NAME` is the ordinary `@p`
582+format but without the leading `~`, so `~sampel-palnet` is specified as
583+`sampel-palnet`. This is typically used in conjunction with `-k` when booting a
584+new ship.
585+
586+- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
587+
588+### `-x, --exit`
589+
590+Run a ship but exist immediately after it starts.
591+
592+- Undocked: `urbit -x [pier]`
593+- Docked: `[pier]/.run -x`
594+
595+### `-X, --scry PATH`
596+
597+Read a ship's state on scry path `PATH`, jamming the result and saving it to
598+`[pier]/.urb/put/[PATH].jam`. The scry path is in the format
599+`/[care]/[path]`, omitting the ship and case elements. For example,
600+`/cx/~zod/base/~2022.6.2..11.27.40..8f56/gen/code/hoon` would be
601+`/cx/base/gen/code/hoon`.
602+
603+- Undocked: `urbit -X /cx/base/gen/code/hoon [pier]`
604+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon`
605+
606+### `-Y, --scry-info FILE`
607+
608+Optional name for the file produced by a scry performed with `-X`, rather than the scry path.
609+
610+- Undocked: `urbit -X /cx/base/gen/code/hoon -Y foobar [pier]`
611+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Y foobar`
612+
613+### `-Z, --scry-format FORMAT`
614+
615+Optionally specify the output format for the file produced by a `-X` scry. The
616+format may either be `jam` to produce a jam file, or else an aura. If it's an
617+aura, the leading `@` is omitted, so `@ud` is specified as `ud`. If an aura is
618+specified, the resulting atom is encoded in a text file with that aura's
619+formatting. If an aura is specified, the scry endpoint must produce an atom, not
620+a cell.
621+
622+- Undocked: `urbit -X /cx/base/gen/code/hoon -Z ud [pier]`
623+- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Z ud`