@@ -1,274 +0,0 @@
1−---
2−next: true
3−sort: 2
4−title: Appliances
5−---
6−
7−# Appliances
8−
9−You've built and launched your urbit. How do you control it
10−securely? Three ways: through the Unix console, over the Web,
11−or via an Urbit moon.
12−
13−What are you controlling, anyway? A user-level application on
14−Urbit is called an "appliance." Think of an appliance as like a
15−Unix process that's also a persistent database.
16−
17−By default, your urbit is running two appliances, the `:dojo`
18−shell and the `:talk` messenger. For more advanced information
19−about your appliance state, see the end of this document.
20−
21−## Console
22−
23−The Unix console is the most basic way you talk to apps. You've
24−already used it a bit, but let's do more.
25−
26−The Urbit command line is a little like the Unix command line,
27−but different. It's also a little like a window manager.
28−
29−Your Unix terminal is separated into two parts: the prompt (the
30−bottom line) and the record (the rest of your screen).
31−
32−The record is shared; all the output from all the apps in your
33−command set appears in it. So you'll see `:talk` messages while
34−working in the dojo.
35−
36−The prompt is multiplexed; you switch the prompting app with
37−`^X`. Pressing return sends the prompt line to the app. Urbit
38−does not automatically echo your input line into the record,
39−the way a normal Unix console does.
40−
41−Also unlike a normal Unix console, the application can process
42−your input before you hit return. In general, invalid input is
43−rejected with a beep. Incorrect input may even be corrected!
44−Yes, this is highly advanced console technology.
45−
46−Like many but not all Unix command lines, Urbit has built-in
47−history editing. You've never seen anything like these
48−innovative key bindings before:
49−
50− ^A cursor to beginning of the line (Home)
51− ^B cursor one character backward (left-arrow)
52− ^E cursor to the end of the line (End)
53− ^F cursor one character forward (right-arrow)
54− ^G beep; cancel reverse-search
55− ^K kill to end of line
56− ^L clear the screen
57− ^N next line in history (down-arrow)
58− ^P previous line in history (up-arrow)
59− ^R reverse-search
60− ^T transpose characters
61− ^U kill to beginning of line
62− ^Y yank from kill buffer
63−
64−`^C` is processed at the Unix layer, not within Urbit. If
65−there's an event currently running, ^C interrupts it and prints a
66−stack trace -- useful for finding infinite loops.
67−
68−`^D` from `:talk` or `:dojo` stops your Unix process. From any
69−other app, it removes the prompting app from the command set.
70−
71−Pressing left-arrow or `^B` at the start of a line is an input
72−operation with the metaphorical meaning "get me out of here,"
73−ie, escape. The exact semantics of an escape are application
74−dependent.
75−
76−## Web
77−
78−For now, we'll keep assuming you're at `http://localhost:8080`.
79−But for planets only, we also proxy web domains through Urbit's
80−own servers. Any planet `~fintud-macrep` is also at
81−`fintud-macrep.urbit.org`. Please use this proxy as little as
82−possible; it's not well-optimized.
83−
84−There's a web interface to `:talk` at
85−
86− http://localhost:8080/~~/home/pub/talk
87−
88−and a dojo interface at
89−
90− http://localhost:8080/~~/home/pub/dojo/fab
91−
92−The `:talk` client is beautiful and works quite well. Use it.
93−The `:dojo` client is a bit more of a work in progress. (For
94−instance, you can't paste text into it.)
95−
96−The login flow remains rather a work in progress. It's not at
97−all secure. But the first time you use an Urbit app (not just a
98−generated page -- you can tell by the `~~` in the URL), it will
99−prompt you for a password.
100−
101−In a righteous world, the password would be (or default to) your
102−initial ticket. Since the world is lawless and filled with evil,
103−just hit return and send a empty password. The real password
104−will be printed on your console.
105−
106−A URL that starts with `/~~/` authenticates your web page as the
107−same urbit as the server. If instead of `/~~/` you write
108−`/~fintud-macrep/` (you're using an app on someone else's urbit,
109−and want to sign in as yourself), you'll authenticate with a
110−single-signon flow. Don't worry, only your own urbit ever sees
111−your password. Once you log in, a cookie is set and you don 't
112−need to do it again.
113−
114−Internally, Urbit treats every web page as another urbit; even a
115−request with no `/~~/` or `/~fintud-macrep/` is an anonymous
116−comet. Appliances actually can't tell whether they're talking to
117−an urbit over `%ames`, or a browser over HTTP.
118−
119−### Enabling HTTPS
120−
121−Urbit doesn't yet serve HTTPS directly. But when you route
122−through `urbit.org`, you can also use HTTPS. Our server handles
123−your HTTP request and proxies it over Urbit. Of course we could
124−MITM you, but we won't. If you want HTTPS on your own urbit, use
125−the "secure" port shown on startup:
126−
127− http: live ("secure") on 8443
128−
129−Firewall off this port. Get an nginx or other outer server. Put
130−your SSL certificate in it and reverse-proxy to `8443`.
131−
132−## An Urbit moon
133−
134−The fanciest way to control your urbit is through Urbit itself:
135−a moon, or satellite urbit. Sadly, only planets can have moons.
136−
137−In this setup, you have a planet running on a box in the cloud,
138−and a moon on your laptop or other mobile. Changes to the planet
139−automatically propagate to the moon. Also, the moon's console is
140−linked to the `:talk` appliance on the planet, so you communicate
141−as yourself.
142−
143−To build your moon, just run
144−
145− ~fintud-macrep:dojo> +moon
146−
147−This will generate a plot and a ticket. The plot will be a
148−64-bit plot within your planet, like `~mignel-fotrym-fintud-macrep`.
149−On your laptop, install Urbit:
150−
151− urbit -w $plot -t $ticket
152−
153−You'll get an urbit where ^x will switch you back and forth
154−between the two prompts:
155−
156− ~mignel-fotrym-fintud-macrep:dojo>
157− ~fintud-macrep:talk()
158−
159−Your moon's `%home` desk is already synced to the `%kids` desk on
160−your planet. If you want changes on your moon's `%home` to sync
161−back into your planet's `%home`,
162−
163− ~fintud-macrep:dojo> |sync %home ~mignel-fotrym-fintud-macrep
164−
165−## Urbit internals
166−
167−As a user of any machine, you can't help understanding the
168−machine on more or less the same terms as its engineers. You
169−should at least know what the major components are.
170−
171−### Source code
172−
173−Urbit is a "run-from-repository" OS; all code ships as source on
174−your own urbit, in the revision-control vane `%clay`. Better
175−yet, live code in every layer updates itself when the source
176−changes. If the local source is subscribed to a remote
177−publisher, the update process is "evergreen" and automatic.
178−
179−There are five major layers of code in Urbit. Layer 1 is the
180−kernel (`arvo/hoon.hoon`), which includes both the Hoon compiler
181−and the Arvo event loop. Layer 2 is the main library
182−(`arvo/zuse.hoon`), Layer 3 is the kernel modules or "vanes"
183−(`arvo/*.hoon`). Layer 4 is appliances, marks, and fabricators
184−(`ape/*.hoon`, `mar/*.hoon`, `fab/*.hoon`), run from the `%gall`
185−and `%ford` vanes. Layer 5 is generators (`gen/*.hoon`), run
186−from the `:dojo` appliance.
187−
188−The kernel (layer 1), the vanes (layer 3) and the apps (layer 4)
189−are stateful; their state is typed, and of course needs to be
190−preserved across code updates. If the new state type differs,
191−the developer must provide a state adaptor. If compilation fails,
192−the new code is disregarded and retried again on the next change.
193−
194−Appliances are like Unix daemons, except persistent and permanent.
195−But they are the only process-like constructs in Urbit. While
196−Unix uses many short-lived processes that are not daemons, Urbit
197−invokes simple tasks in simple contexts. In Unix terms: since
198−the `ls` process is not meant to run forever and/or have side
199−effects, giving it the power to do so is asking for trouble. In
200−Urbit, the layer 5 dojo generator `+ls` is a pure function which
201−simply produces some typed output.
202−
203−You should never have to worry about any of this stuff; we're
204−just describing it here so it's not a mystery.
205−
206−### Appliances
207−
208−Your main configuration task is choosing (a) what appliances
209−on your urbit should be running (the *active set*), and (b) what
210−appliances your console should be linked to (the *command set*).
211−Again, ^X switches the console prompt between appliances in (b).
212−
213−Why are these different sets? First, some apps don't need a
214−command prompt. Your urbit runs three default apps: `:talk`,
215−`:dojo`, and `:hood`. The hood is a system appliance and has no
216−direct UI (you control it through the dojo).
217−
218−Second, you can also link your console to apps on other urbits,
219−and put those connections in the command set. Essentially, the
220−console is also `ssh` or `rlogin`. The console is just another
221−appliance (it's actually the `drum` library within `:hood`),
222−and Arvo is good at routing events over the network.
223−
224−What is an appliance or "app," anyway? An app, basically. Think
225−of a Unix daemon, except that (1) it only responds to events and
226−can't run continuously ("nonpreemptive"); and (2) it's
227−"permanent" (never exits, dies, or is even reset).
228−
229−Why do appliances live forever? They have to. An appliance name
230−is also a sort of port in the Internet sense. A conversation
231−with appliance X on urbit Y is one conversation, not a sequence
232−of disconnected activations.
233−
234−An appliance is always sourced from a path which is a function of
235−its name, from `%foo` to `/===/ape/foo/hoon`. In this path, the
236−urbit is self; the version is now. The desk defaults to `%home`;
237−changing it will adapt the appliance state.
238−
239−The normal way to run code written by some external developer is
240−to merge (one time) or sync (for continuous upgrades), the
241−publisher's distribution desk, to a desk on your own urbit.
242−Obviously a desk per vendor is ideal, which also lets you
243−"sidegrade" an app to a different vendor by switching desks.
244−
245−### Configuration commands
246−
247−Initially, your command set is `:talk` and `:dojo`; your active
248−set is `:talk`, `:dojo` and `:hood`. It's completely fine to
249−never even think about changing this, but...
250−
251−#### `|link $?([app=term ~] [who=plot app=term ~])`
252−
253−Link your console to an existing appliance, putting it in the
254−command set. If no plot is specified, it's an appliance on your
255−own urbit.
256−
257− |link %dojo
258− |link ~tasfyn-partyv %dojo
259−
260−Permission is up to the appliance, of course.
261−
262−#### `|unlink $?([app=term ~] [who=plot app=term ~])`
263−
264−The opposite of `|link`. Same interface.
265−
266−#### `|start [app=term $|(~ [syd=desk ~])]`
267−
268−Start an appliance, adding it to the active set. If `syd` is not
269−specified, the desk is `%home`:
270−
271− |start %foo
272− |start %foo %away
273−
274−If the appliance is running, `|start` sets its desk instead.