@@ -1,623 +0,0 @@
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`