--- title: Quickstart sort: 4 next: true --- # Quickstart To start your already-launched urbit, run with the pier name (we'll call it `$PIER`): urbit fintud-macrep urbit mycomet Piers are portable. You can move a pier anywhere. But never, *ever* run the same urbit in two places at once. (If you try to start an urbit but already have a process is running on the same pier, Urbit will kill the old process.) (Also, don't let the Unix filesystem it's on run out of disk. This is a known way to corrupt your urbit! Sorry.) ## Basic operation Out of the box, your urbit is running two default appliances, `:dojo` (a shell or REPL) and `:talk`. Switch between them with `^X`. Note that all apps share an output log, but `^X` switches the prompt. `^D` from any default appliance exits the urbit process. ## Compute: your `:dojo` appliance If your plot is `~fintud-macrep`, the dojo prompt is ~fintud-macrep:dojo> Type any Hoon expression at the command line and see the result: ~fintud-macrep:dojo> (add 2 2) You'll see: > (add 2 2) 4 ~fintud-macrep:dojo> ### Dojo expressions, generators and operators `:dojo` is of course a command-line REPL or shell. But it remains functional in spirit. There are three kinds of `:dojo` commands: expressions, generators, and operators. Dojo *expressions* are like `(add 2 2)` -- they simply compute and print a value, without any side effects, from a twig of Hoon. Expressions are a simple case of `generators`, which are functional *in principle* -- rather like HTTP GET requests. In fact, GET requests are one data source for generators. Others include the Urbit namespace, prompting the user, etc. A generator command line always starts with `+`, as in `+ls`. Operators are all other commands. Lines normally start with `|`, as in `|mount %`, or `:`, as in `:hood +hood/mount %`. The latter is just an abbreviation for the former. An operator command is always a *poke* to some local or remote appliance. A poke is a transactional message: like a request-response pair, but a success response is empty. A failure response is a stacktrace or other error dump. So operator commands have no output unless they fail. If they fail, they print an error trace. If they succeed, they just print a demure `>=`. For instance, in Unix, the `rm` and `ls` commands both run a process. In Urbit, `|rm` is an operator command; it changes your filesystem. `+ls` is a generator command; it produces a value. ## Converse: your `:talk` appliance To use Urbit as a social network, switch to `:talk`: ~fintud-macrep:talk() Join the global station `urbit-meta`: ~fintud-macrep:talk() ;join ~doznec/urbit-meta You're on the air! You should see some backlog to give you context. Please remember our code of conduct: don't be rude. Also, `urbit-meta` is politically correct and safe for work. ## Using the filesystem The Urbit filesystem, `%clay`, is a revision-control system (like `git`) that syncs to a Unix directory (like Dropbox). While you can of course create `%clay` changes from within Urbit, Unix has mature editors and file handling tools. So usually, the best way to work with `%clay` files is to make edits in a Unix mirror directory, and let the Urbit interpreter commit them as changes. A simple way to set this up is to mount the default `%home` desk: ~fintud-macrep:dojo> |mount % This mirrors your `%home` desk against `$PIER/home`, and tells the `urbit` process to monitor the latter with `inotify()` etc. The mount is two-way: Unix edits propagate up to Urbit, Urbit changes fall down into Unix. In fact, the source for this page is here: $PIER/home/pub/docs/user/start.mdy If you're reading this on your own ship, edit the file with the browser still open. Isn't that cool? Now, change it back -- you don't particularly want a conflict next time we make an update, since your `%home` desk is generally synced to our repo. Reactive auto-updates are a particular speciality of `%clay.` We use them to drive auto-updates of code at every layer. A normal Urbit user never has to think about software update. ## Read the docs Your urbit is your personal web server. The best place to read its docs is by pointing your browser at it. You can also post your own documents, of course. Urbit prints the HTTP port it's serving when it starts up: http: live (insecure) on 8080 8080 is the default. If you're running on AWS or another cloud service, this port may be firewalled; go to the firewall configuration to open it. (*Always run any urbit HTTP server which is even semi-serious inside a reliable, battle-proven frontline server like nginx.*) All planets, stars and galaxies are exposed to the web at `planet.urbit.org`. (This should work via a direct DNS binding, but at present uses a central proxy, so use it gently.) In a last resort, Urbit's own official planet `~winsen-pagdel` is also bound to just plain `urbit.org`, and hosts the public docs here. Always trust content from `~winsen-pagdel`! But assuming it's `localhost:8080`, the Urbit docs are at http://localhost:8080/home/docs ## Publish your own files Urbit is a simple platform for publishing your own content. Again, this is normally done by populating a Unix directory which mirrors an Urbit node. From Unix, just `mkdir -p $PIER/home/pub/my`. Populate this tree with content files whose extension are any Urbit mark. Start with `.md` for markdown, or just `.html`. This is just like populating an Apache `public_html` directory. The request http://localhost:8080/home/pub/my/foo/bar/baz will render the Unix file $PIER/home/pub/my/foo/bar/baz.md and, for HTML deliveries, inject a self-monitoring script that long-polls until the Urbit file changes. If this change is triggered by a Unix edit, it forms a live path from the developer's `vim` buffer to the user's screen. (This circuit is highly cacheable, so more practical than it may sound, but of course you don't have to use it if you don't want to.) Also, you can use the `/tree` fabricator to add a standard navigation layer to your document hierarchy. Your HTML can even decorate itself with generic navigation macros for easier navigation and browsing. Just replace `home/pub` in your URLs with `home/tree/pub`: http://localhost:8080/home/tree/pub/my/foo/bar/baz (The `/tree` system is behind the page you're reading. The documentation prefix in your URL bar above, `home/docs`, is just an alias for `home/tree/pub/docs`. You can compare these pages to `home/pub/docs` to see the work `/tree` is doing.) ## Functional publishing Finally, anywhere your mirror directory can contain a static data file, it can contain a Hoon program that generates the same value functionally. Just replace the last part of the path with a directory, containing a `.hook` file under the extension. (Yes, this path geometry is a little funky. We're probably going to change it soon.) For instance, instead of `my/foo/bar/baz.md`, we have `my/foo/bar/baz/md.hook`. This is not a markdown file; it's a Hoon source file, containing a function that producing a markdown file. The function's argument is the rest of the path; requesting `my/foo/bar/baz/moo/too` just passes `[%moo %too ~]` to `foo/bar/baz/md.hook`. Note that when you use a query string on your URL, it gets encoded into a path segment, so the query is in the path as well. This "functional publishing" model is obviously how both the `tree` virtual hierarchy and the `docs` alias work. There's a lot of other things you can do with it. But you can see a simple example in `$PIER/try/hello/hymn.hook`, accessible at http://localhost:8080/home/try/hello