3description = "How to operate your ship, including using your ship's filesystem and messaging applications, starting a moon, or requesting a DNS entry."
6aliases = ["docs/using/messaging/", "docs/using/admin/"]
11This document deals with:
13- Running an Urbit ship with the ordinary runtime [from the command line](/getting-started/cli).
14- Basic setup, configuration and usage in Urbit's shell called the `dojo`.
16If you're looking for information on using the GUI application [Port](/getting-started#port), see the [Port guide](/using/running/port) instead.
20You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.
22You can force-quit your urbit with `Ctrl-z` from anywhere.
26To restart your urbit simply pass the name of your pier:
40To log an urbit's command line output to a file, use `script`:
43$ script urbit.log ./urbit your-urbit
48Piers are designed to be portable, but it _must_ be done while the urbit
49is not running. Urbit networking is stateful, so you can't run two copies
50of the same urbit in two places.
52To move a pier, simply move the contents of the directory it lives in.
53To keep these files as small as possible we usually use the `--sparse`
54option in `tar`. With a pier `your-urbit/`, something like this should work:
57tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
58scp your-old-server:~/your-urbit.tar.gz your-new-server:~
61Then to unzip it, on your other Unix server, run:
64tar xfvz your-urbit.tar.gz
67Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:
73## Hardware requirements
75Urbit can run on any x86 computer (unofficial, unsupported [ARM binaries](https://botter-nidnul.github.io/AArch64_Urbit_Static_Binaries.html) are also available), ideally with at least 2GB of RAM.
77Urbit maintains a persistent log of the history of your ship. Eventually this log will be automatically trimmed when necessary, but for now it only increases in size. An actively used planet will consume 5-50 GB of storage space per year of operation.
81Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.
83In the CLI, Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no Dojo command or Hoon expression that starts with ')', the Dojo rejects it.
85`Ctrl-x` - Switches the prompt between running console apps
87`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack
90`Ctrl-d` - From Chat or Dojo, stops your Urbit process.
92`Ctrl-z` - Stops the Urbit process from _anywhere_.
94`↑` / `↓` - History navigation
96The following emacs-style key bindings are available:
99Ctrl-a Cursor to beginning of the line (Home)
100Ctrl-b Cursor one character backward (left-arrow)
101Ctrl-e Cursor to the end of the line (End)
102Ctrl-f Cursor one character forward (right-arrow)
103Ctrl-g Beep; cancel reverse-search
104Ctrl-k Kill to end of line
105Ctrl-l Clear the screen
106Ctrl-n Next line in history (down-arrow)
107Ctrl-p Previous line in history (up-arrow)
109Ctrl-t Transpose characters
110Ctrl-u Kill to beginning of line
111Ctrl-y Yank from kill buffer
116By default, your `%base` [desk](/docs/glossary/desk) (which contains the [Arvo](/docs/glossary/arvo) kernel and core apps) receives updates ([OTAs](/docs/glossary/ota-updates)) from your sponsor. Other desks will receive updates from their respective publishers. To check the OTA source for each desk, run `+vats` in the [dojo](/docs/glossary/dojo). It will print out details for each desk - the `source` field shows which ship the desk gets updates from and the `updates` field shows `tracking` if automatic updates are enabled.
118If for some reason updates are not enabled or the current source is not online or up to date, you can enable updates or change source with the `|install` command.
120`|install (sein:title our now our) %landscape` will enable updates to the `%landscape` desk from your sponsor. `|install ~some-ship %landscape` will enable updates to the landscape desk from whatever ship is specified in place of `~some-ship`. For third party apps, make sure to correctly specify the publisher's ship. Each desk's updates are managed separately, so you'll need to run this for each desk separately. For the `%base` desk specifically, you sync from `%kids` rather than `%base` on the remote ship, so must specify it like `|install (sein:title our now our) %kids, =local %base`.
122#### Additional OTA Troubleshooting
124Please check the Support Wiki for additional OTA troubleshooting, such as:
125[OTA 1.0.71 failed](https://github.com/urbit/support/wiki/OTA-1.0.71-failed),
126[Missing OTA](https://github.com/urbit/support/wiki/Missing-OTA),
127[Stuck flow preventing planets from receiving
128OTAs](https://github.com/urbit/support/wiki/Stuck-flow-preventing-planets-from-receiving-OTAs),
129and [No content shows in Links page after OTA](https://github.com/urbit/support/wiki/No-content-shows-in-Links-page-after-OTA).
133On startup, urbit tries to bind to `localhost:80`. If you're already running something on port `80`, or your host OS will not allow urbit to bind port `80`, urbit will try `8080`, then `8081`, `8082`, and so on. For planets only, we also provide subdomains of `arvo.network` for free. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-setup).
135Once running, you can sign into your ship’s web interface from `http://localhost` (if bound to port `80`), `http://localhost:8080` (if bound to port `8080`), or `https://your-urbit.arvo.network` if you've set up DNS.
139Planets can spawn moons, which are conceptually meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
141To generate a random moon from your planet, run:
144~sampel-palnet:dojo> |moon
145moon: ~faswep-navred-sampel-palnet
1460w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SIEUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1
149The `moon:` part is the name of the moon, in this case `~faswep-navred-sampel-palnet`. The next line starting with `0w5...` is the private key necessary to boot it.
151You can just copy the key (which in this case would be the `0w5[...]600g1` part) to the clipboard, or save it in a `.key` file, for example `faswep-navred-sampel-palnet.key`.
153You can use the key and moon name in the same installation flow from the [Command line installation](/getting-started/cli) guide, following the same scheme as for booting a planet. That scheme is:
156$ ./urbit -w <moon-name> -G <key> -c <pier-name>
162$ ./urbit -w <moon-name> -k <key-file> -c <pier-name>
165Note the `<moon-name>` excludes the leading `~`. The `-c <piername>` argument is not required, but it is recommended; otherwise, the resulting directory is a rather unwieldy moon name. Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
167To factory reset a moon -- that is, to reset its presence on the network so that it's treated as a freshly spawned ship by others -- run from the parent ship:
170|moon-breach ~faswep-navred-sampel-palnet
173To cycle the keys of a moon without a factory reset, run:
176|moon-cycle-keys ~faswep-navred-sampel-palnet
179You can then run `|rekey` on the moon with the key given by the above command as the argument.
181### Maintaining Moons Through A Breach {#restoring-moons}
183Moons are [always subordinate to the ship that issued them](/docs/glossary/moon). Their PKI is sent around the network by their parent planet/star/galaxy. As such, if the sponsor planet/star/galaxy of a moon breaches, other urbits on the network who were not aware of the moon prior to the breach (knew its PKI information) will not be able to reach the old moon. Moons can, however, be preserved over the breach of their sponsor and re-added to `jael`. The following guide assumes you are on `[life=n rift=1]` where `n` can be any life #. If you've previously breached your moon and want to preserve it, you'll need to modify the instructions to include setting the appropriate rift using `|moon-breach` from `hood`.
185To add an existing moon to `jael` on a breached planet, you'll need the following:
187 - Your moon's current life # `+keys ~sampel-monler-dozzod-dozzod` (run on the moon) _and_;
188 - Your moon's sponsor's understanding of your moon's current life (same command, run on the sponsor).
189 - Your moon's existing keyfile or key-string (`@uw`) _or_ the result of `pub:ex:(nol:nu:crub:crypto .^(@uv %j /=vein=/<life # of moon, per moon, here>))` _and_;
190 - Your moon's sponsor's understanding of your moon's existing public key `pass:.^([@ud pass=@uw ~] %j /=deed=/~sampel-monler-dozzod-dozzod/<life # of moon per sponsor here>)`.
192If you only have they keyfile or key-string from your moon's last boot, you'll need to derive the `pass` value from that using `pub:ex:(nol:nu:crub:crypto key:(seed:jael:l (cue <your @uw keyfile contents or key-string contents here>)))`. This should produce a long `@ud`.
194Once you have all of the requisite elements, you can perform the following on the moon's sponsor:
197|moon-cycle-keys ~sampel-monler-dozzod-dozzod, =life <life # of moon, per moon, here>, =public-key <result of the existing keyfile conversion to pass or the result of scrying jael on your moon, found above>
200Eventually, the PKI will populate through the network w/ the correct life #, reconnecting your previously orphaned moon. You can speed this up by `|hi ~zod` and `|hi ~sampel-monler-dozzod-dozzod`-ing from the moon and sponsor, respectively (replace with the appropriate ship names).
204## Escaping A Sponsor {#escape}
206To use the network as a planet or star, you must be sponsored by an active star
207or galaxy, respectively. If your sponsor isn't suiting your needs, you can
208escape to a different one. This can be done with
209[Bridge](https://bridge.urbit.org/) following the instructions
210[here](/using/id/using-bridge#escaping-your-sponsor).
212## Life and rift number
214You can check your ship's _life_ and _rift_ number by running `+keys our` in
215dojo. You can inspect another ship's life and rift number by running `+keys ~sampel-palnet`. For information on what life and rift are, see [Life and Rift](/docs/azimuth/life-and-rift).
217## DNS setup {#dns-setup}
219We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface. Stars and planets follow the same DNS request process, and galaxies have their own requirements. Moons and comets are not supported.
221For a planet or star's DNS request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.
223To initiate a DNS request, run the following thread in your ship's dojo, passing the IP address as an argument with .0.0.0.0 (`@if`) syntax. For example:
226-dns-address [%if .1.2.3.4]
229The `%dns-address` thread, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `couldn't access ship on port 80` message in the terminal; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, the `%dns-address` thread will print a terminal message saying `awaiting response from ~zod`.
231The request will make take a little time to be fulfilled, but eventually the `ship.arvo.network` DNS record will be set to the given IP address. Once that's set up, `~zod` will be notified and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying, `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain and say `confirmed access via ship.arvo.network`.
233Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
237To enable SSL on your ship, you must poke the `%acme` agent with the domain encoded in a path and it will request a certificate. The path format is `/tld/your_domain/your_subdomain`, so if your domain is `sampel-palnet.arvo.network`, you'd use it like so:
240:acme &path /network/arvo/sampel-palnet
245Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.
247There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
253This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.
255Otherwise, `-dns-auto` works the same as `-dns-address` does with stars and planets: if it's available or unavailable, terminal messages, and so on.
259The built-in logic for listening on port 80 is to try to bind to port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent versions of macOS. Otherwise, the process needs to either be run as root, or be given special permission (`sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit/binary` on Linux).
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list