@@ -1,623 +0,0 @@
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: 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.
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)).
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`.
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.
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
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):
57−urbit -c some-pier-name
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.
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`.
68−To boot a moon, planet, star or galaxy, you must use two arguments:
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).
75−urbit -w sampel-palnet -k /path/to/my.key
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.
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.
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`.
91−If a ship has already been boostrapped, you can run it by simply specifying the
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.
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
109−To create one, you just use the `-F` option and specify the name of a ship
118−**Note the ship should be shut down before using either of the utilities described below.**
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.
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.
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.
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.
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.
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.
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:
151−urbit dock /path/to/pier
154−Afterwards, you'll be able to just do `/path/to/pier/.run` and can delete the
155−separate `urbit` binary.
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.
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`.
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
177−- Undocked: `urbit cram [pier]`
178−- Docked: `[pier]/.run cram`
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
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
194−- Undocked: `urbit dock [pier]`
195−- Docked: `[pier]/.run dock`
197−Note the auto-dock behavior when booting new ships can be disabled with the
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.
205−- Undocked: `urbit grab [pier]`
206−- Docked: `[pier]/.run grab`
210−Print pier information.
212−- Undocked: `urbit info [pier]`
213−- Docked: `[pier]/.run info`
219−live: loaded: MB/268.173.312
220−boot: installed 351 jets
222−urbit: zod at event 256133
223− disk: live=&, event=256133
226− map size: 1099511627776
228− max pages: 268435456
229− number of pages used: 1506786
230− last transaction ID: 255733
232− number of readers used: 0
233− file size (page): 6171795456
234− file size (stat): 6171795456
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`.
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.
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.
250−- Undocked: `urbit meld [pier]`
251−- Docked: `[pier]/.run meld`
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.
258−- Undocked: `urbit pack [pier]`
259−- Docked: `[pier]/.run pack`
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
268−- Undocked: `urbit prep [pier]`
269−- Docked: `[pier]/.run prep`
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.
276−- Undocked: `urbit next [pier]`
277−- Docked: `[pier]/.run next`
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`.
285−- Undocked: `urbit queu [pier] 10000`
286−- Docked: `[pier]/.run queu 10000`
290−Download a binary. `DIR` is an output directory (it must already exist) and `ARGS` are:
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`.
299−- Undocked: `urbit 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−Note this utility is for kernel development purposes and has a programmatic
306−interface, it does not have a user interface.
308−- Undocked: `urbit serf [pier] [key] [flags] [cache-size] [at-event]`
312−Below are all the options/flags/arguments that can be given to the urbit
317−When booting a new ship, use directory `DIR` for the initial `%base` desk sync,
318−rather than the one in the pill.
321−urbit -w sampel-palnet -k /path/to/my.key -A /path/to/arvo
324−### `-b, --http-ip IP`
326−Bind the HTTP server to IP address `IP`.
328−- Undocked: `urbit -b 192.168.1.10 [pier]`
329−- Docked: `[pier]/.run -b 192.168.1.10`
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))
337−### `-B, --bootstrap PILL`
339−When booting a new ship, use file `PILL` for the pill, rather than the default
340−one fetched from `https://bootstrap.urbit.org`.
343−urbit -w sampel-palnet -k /path/to/my.key -B /path/to/the.pill
346−### `-c, --pier PIER`
348−When booting a ship, name its pier as `PIER` rather than the usual `@p`.
350−- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -c foobar`
352−The pier folder will be named `foobar` as a result of the above command.
354−### `-C, --memo-cache-limit LIMIT`
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
360−- Undocked: `urbit -C 50000 [pier]`
361−- Docked: `[pier]/.run -C 50000`
365−Run the ship in daemon mode. The process will be detached from the terminal
368−- Undocked: `urbit -d [pier]`
369−- Docked: `[pier]/.run -d`
371−### `-e, --ethereum URL`
373−Use the Ethereum gateway at `URL` rather than the default.
375−- Undocked: `urbit -e https://the.url [pier]`
376−- Docked: `[pier]/.run -e https://the.url`
378−### `-F, --fake SHIP`
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.
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).
396−- Undocked: `urbit -g [pier]`
397−- Docked: `[pier]/.run -g`
399−### `-G --key-string STRING`
401−Boot a new ship with private key `STRING`.The private key is `@uw` format. See
402−`-k` for an alternative.
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`
406−### `--http-port PORT`
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.
411−- Undocked: `urbit --http-port 8085 [pier]`
412−- Docked: `[pier]/.run --http-port 8085`
414−### `--https-port PORT`
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
423−Note this is for secure HTTPS only, see `--http-port` for insecure HTTP.
425−- Undocked: `urbit --https-port 8443 [pier]`
426−- Docked: `[pier]/.run --https-port 8443`
428−### `-I, --inject FILE`
430−Inject the event stored in `FILE` jamfile.
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.
436−- Undocked: `urbit -I /path/to/file.jam [pier]`
437−- Docked: `[pier]/.run -I /path/to/file.jam`
439−### `-j, --json-trace`
441−Create JSON trace files in `[pier]/.urb/put/trace`.
443−This runs a tracing profiler, and produces JSON output compatible with
446−- Undocked: `urbit -j [pier]`
447−- Docked: `[pier]/.run urbit -j`
449−### `-J, --ivory-pill PILL`
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.
455−- Undocked: `urbit -J /path/to/ivory.pill [pier]`
456−- Docked: `[pier]/.run -J /path/to/ivory.pill`
458−### `-k, --key-file KEYS`
460−Boot a new ship with the private key file `KEY`. See `-G` for an alternative.
462−- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
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
470−- Undocked: `urbit -L [pier]`
471−- Docked: `[pier]/.run -L`
473−### `-n, --replay-to NUMBER`
475−Replay up to the specified event `NUMBER`.
477−- Undocked: `urbit -n 10000 [pier]`
478−- Docked: `[pier]/.run -n 10000`
480−A snapshot will be saved in a jamfile at `[pier]/.urb/roc/[NUMBER].jam`.
484−Disable the control pane unix socket.
486−- Undocked: `urbit --no-conn [pier]`
487−- Docked: `[pier]/.run --no-conn`
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.
495−- Undocked: `urbit --no-dock -w sampel-palnet -k /path/to/my.key`
497−### `-p, --ames-port PORT`
499−Set the Ames UDP port to `PORT`. This is the port used for inter-ship
502−- Undocked: `urbit -p 33333 [pier]`
503−- Docked: `[pier]/.run -p 33333`
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.
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`.
514−- Undocked `urbit -P [pier]`
515−- Docked `[pier]/.run -P`
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
523−- Undocked: `urbit -q [pier]`
524−- Docked: `[pier]/.run -q`
526−### `-r, --replay-from NUMBER`
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
533−- Undocked: `urbit -r 10000 [pier]`
534−- Docked: `[pier]/.run -r 10000`
538−Report Vere build info.
545−openssl: OpenSSL 1.1.1n 15 Mar 2022
552−- Undocked: `urbit -R [pier]`
553−- Docked: `[pier]/.run -R`
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
562−- Undocked: `urbit -t [pier]`
563−- Docked: `[pier]/.run -t`
565−### `-u, --bootstrap-url URL`
567−Boot a new ship, using the pill fetched from `URL` rather than the default one.
569−- Undocked: `urbit -w sampel-palnet -k /path/to/my.key -u http://example.com/the.pill`
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`.
576−- Undocked: `urbit -v [pier]`
577−- Docked: `[pier]/.run -v`
579−### `-w, --name NAME`
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
586−- Undocked: `urbit -w sampel-palnet -k /path/to/my.key`
590−Run a ship but exist immediately after it starts.
592−- Undocked: `urbit -x [pier]`
593−- Docked: `[pier]/.run -x`
595−### `-X, --scry PATH`
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`.
603−- Undocked: `urbit -X /cx/base/gen/code/hoon [pier]`
604−- Docked: `[pier]/.run -X /cx/base/gen/code/hoon`
606−### `-Y, --scry-info FILE`
608−Optional name for the file produced by a scry performed with `-X`, rather than the scry path.
610−- Undocked: `urbit -X /cx/base/gen/code/hoon -Y foobar [pier]`
611−- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Y foobar`
613−### `-Z, --scry-format FORMAT`
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
622−- Undocked: `urbit -X /cx/base/gen/code/hoon -Z ud [pier]`
623−- Docked: `[pier]/.run -X /cx/base/gen/code/hoon -Z ud`