@@ -10,9 +10,10 @@ files.
1010
1111| App | Description | Source | Build |
1212|---|---|---|---|
13+| `%accountability` | Watches all 256 galaxies from your ship. Every 10 minutes it checks each one's keys on chain, whether it answers, and which `%kids` OTA it serves, and logs every change. A dashboard at `/apps/accountability` and a public JSON API show the results. It needs `%azimuth` running, as on a livenet ship. | [sigilante/accountability](https://github.com/sigilante/accountability) | `nix build .#accountability` |
1314| `%deskjam` | Install and update apps, and upload and download desks, as deskjam files, in your ship's web interface at `/apps/deskjam`. A fork of [tinnus-napbus/deskjam](https://github.com/tinnus-napbus/deskjam). | [iko-soy/deskjam](https://github.com/iko-soy/deskjam) | `nix build .#deskjam` |
14−| `%hits` | Ranks apps by how many installs they have among the ships around you, which gossip their installs to their Pals and the ships they chat with in Tlon. There's no central server. Its frontend is a glob: see [Frontends](#frontends). A fork of [urbit/hits](https://github.com/urbit/hits). | [iko-soy/hits](https://github.com/iko-soy/hits) | `nix build .#hits` |
15−| `%mcp` | An MCP (Model Context Protocol) server at `/mcp` that lets AI tools use your ship, and a proxy at `/apps/mcp/mcp` that offers its tools together with those of remote MCP and OpenAPI servers. A fork of [gwbtc/urbit-mcp](https://github.com/gwbtc/urbit-mcp). | [tloncorp/mcp](https://github.com/tloncorp/mcp) | `nix build .#mcp` |
15+| `%harness` | Runs AI agents on your ship. Talk to them in its web app at `/apps/harness`, in Tlon, or from an editor, while the ship keeps the conversations, permissions and work. Models come from providers you configure, such as OpenRouter, OpenAI or Anthropic. Its Tlon features need `%groups`. | [mopfel-winrux/urbit-agent-harness](https://github.com/mopfel-winrux/urbit-agent-harness) | `nix build .#harness` |
16+| `%hits` | Ranks apps by how many installs they have among the ships around you, which gossip their installs to their Pals and the ships they chat with in Tlon. There's no central server. It works without `%pals`, but then hears only from the ships you chat with. It only counts apps installed from another ship with `|install`, not ones installed from a deskjam file. Its frontend is a glob: see [Frontends](#frontends). A fork of [urbit/hits](https://github.com/urbit/hits). | [iko-soy/hits](https://github.com/iko-soy/hits) | `nix build .#hits` |
1617| `%shelf` | A public web page that lists the apps your ship publishes, so anyone can install them on their own ship. It answers at `/shelf`, for a reverse proxy to serve at the root of its own domain, and needs `%landscape`, which fresh ships have. | [iko-soy/shelf](https://github.com/iko-soy/shelf) | `nix build .#shelf` |
1718| `%silo` | A file manager for the S3 storage your ship uploads to: add a bucket's credentials, then browse its files and upload new ones. It has no agents of its own, and uses `%storage` from `%landscape`, which fresh ships have. | [arthyn/silo](https://github.com/arthyn/silo) | `nix build .#silo` |
1819
@@ -24,12 +25,13 @@ checkout, give the repo's address instead of `.`, such as
2425itself, at the version `flake.lock` pins.
2526
2627Each build writes `result/<desk>.deskjam`, such as `result/shelf.deskjam`, in
27−place of the last build's `result`. For an app with a web frontend, a glob,
28−it also writes the glob's files next to it, as `result/<desk>-glob`, and the
29−build fails if `flake.nix` doesn't build them, so a deskjam never comes
30−without its glob. `nix build .#hits-glob` or `.#silo-glob` builds just a glob.
31−`nix build .#deskjam .#hits .#mcp .#shelf .#silo` builds all five, into
32−`result`, `result-1`, `result-2`, `result-3` and `result-4`.
28+place of the last build's `result`. For an app whose web frontend is a glob,
29+such as hits, it also writes the glob's files next to it, as
30+`result/<desk>-glob`, and the build fails if `flake.nix` doesn't build them,
31+so a deskjam never comes without its glob. `nix build .#hits-glob` or
32+`.#silo-glob` builds just a glob. `nix build .#accountability .#deskjam
33+.#harness .#hits .#shelf .#silo` builds all six, into `result` and `result-1`
34+to `result-5`.
3335
3436You can install these files on your ship with
3537[iko-soy/deskjam](https://github.com/iko-soy/deskjam): see
@@ -47,7 +49,8 @@ these files. Only install apps you trust: an app's agents, its programs, run
4749as your ship, and can read and change anything on it.
4850
4951If you build on another machine, such as the server your ship runs on, copy
50−the file to the computer your browser runs on first, for example with `scp`.
52+the file, and its `<desk>-glob` folder if it has one, to the computer your
53+browser runs on first, for example with `scp -r`.
5154
5255### Getting deskjam
5356
@@ -81,10 +84,7 @@ After that, update deskjam like any other app, as below.
8184 click **confirm**.
82855. The status page says whether the app runs.
8386
84−Once it runs, see the app's README for how to set it up. mcp's README
85−describes an operator console at `/apps/mcp/`, which this version of mcp
86−doesn't have. MCP clients send mcp's API key in an `X-Api-Key` header, and
87−`.^(@t %gx /=mcp-proxy=/client-key/noun)` in the dojo prints it.
87+Once it runs, see the app's README for how to set it up.
8888
8989### Updating an app
9090
@@ -102,8 +102,7 @@ Apps installed this way don't update on their own. To update one:
102102Uploading the kept copy with **replace it** puts the old version back. If the
103103update changed the state an agent keeps, that usually fails, and nothing
104104changes. But some agents start afresh from state they can't read, and lose it
105−instead: deskjam's and mcp's do. For mcp, that means a new API key, and its
106−remote servers and OAuth grants are gone.
105+instead: deskjam's does.
107106
108107If the app came from another ship with `|install`, kiln, the part of your
109108ship that installs and updates apps, keeps it in sync with that ship. That
@@ -114,23 +113,40 @@ upload with their latest release.
114113
115114### Frontends
116115
117−An app's web frontend, its glob, isn't part of its desk. Landscape's
118−`%docket` agent gets it as the app's docket says, and the build puts it next
119−to the deskjam, as `result/<desk>-glob`:
116+Some apps' web frontends are globs, which aren't part of their desks.
117+Landscape's `%docket` agent gets an app's glob as its docket says, and the
118+build puts the glob's files next to the deskjam, as `result/<desk>-glob`. That
119+folder is what you upload at `/docket/upload`: choose the app's desk and the
120+folder, and click **glob!**. Use a browser other than Safari, which can't
121+upload folders.
120122
121123- silo's docket has `%docket` download its glob from a url, so `silo.deskjam`
122− works on any ship. You need `result/silo-glob` only to serve the frontend
123− from your own ship instead, as deskjam's
124+ works on any ship, with nothing to upload.
125+- hits' docket has `%docket` get its glob from `~donmec-sallud` over Ames,
126+ with a placeholder hash. On your ship, click **set** in the glob box on the
127+ confirm page when you install `hits.deskjam`, so your ship serves the glob
128+ instead, and once hits runs, upload `result/hits-glob`. On
129+ `~donmec-sallud`, hits' docket already names your ship, so just upload the
130+ glob. Without its glob, hits runs, but has no frontend.
131+- To serve silo's frontend from your own ship too, click **set** the same way
132+ and upload `result/silo-glob`, as deskjam's
124133 [Serving a glob from your ship](https://github.com/iko-soy/deskjam/blob/main/docs/globs.md#serving-a-glob-from-your-ship)
125134 says.
126−- hits' docket has `%docket` get its glob from `~donmec-sallud` over Ames,
127− with a placeholder hash, so `hits.deskjam` is for that ship. There, install
128− it, then open `/docket/upload`, choose the desk `hits` and the folder
129− `result/hits-glob`, and click **glob!**. When you update hits with deskjam,
130− click **set** in the glob box on the confirm page first, or hits loses its
131− frontend until you upload it again. Other ships get hits, frontend
132− included, from that ship once it publishes hits:
133− `|install ~donmec-sallud %hits`.
135+
136+When you update an app whose glob your ship serves, click **set** in the glob
137+box on the confirm page first, which keeps the glob your ship serves now.
138+Then upload the new `result/<desk>-glob`, so the frontend matches the new
139+version. If the app was suspended, as after a kernel update, `%docket`
140+forgets its glob when the app starts again, even after **set**: upload it
141+again.
142+
143+To let other ships install an app from yours, frontend included, publish it:
144+`:treaty|publish %hits` makes it public and lists it in Landscape, and
145+`|public %hits` is enough for `|install ~your-ship %hits`.
146+
147+The other apps have no glob: accountability, deskjam, harness and shelf
148+serve their pages from their own agents. harness' frontend is in its desk,
149+so `harness.deskjam` already has it.
134150
135151### Kernel updates
136152
@@ -151,19 +167,36 @@ has the details, including what to do when an upload goes wrong.
151167 `.deskjam` file has the files that repo's own build makes. jammer leaves
152168 out the files a `|commit` would skip too, such as hits' `LICENSE`, which has
153169 no extension.
154−- mcp's repo builds its desk with `zig build`, which copies some files from
155− other repos at pinned commits. `flake.nix` copies the same files from the
156− same commits. After moving mcp's pin, check that its `build.zig` still lists
157− the same files and commits, and change `flake.nix` to match if not: nothing
158− checks this for you.
170+- accountability has no flake, and its `desk/` is the whole desk, which
171+ `flake.nix` packs as it is.
172+- harness' repo builds its desk with `zig build`. It builds `fe/`, its
173+ frontend, into the desk's `web/`, which harness' own agent serves; fetches
174+ grubbery and some of Tlon's files with git, at commits it pins; and patches
175+ grubbery's desk under harness' own. `flake.nix` runs the same `zig build`
176+ with npm's packages fetched ahead, and a stand-in `git` that answers from
177+ inputs pinned to the same commits, and fails if the build asks for any
178+ other: when a new version of harness pins other commits, move
179+ `harness-grubbery` or `harness-tlon` to them. The build also fails if the
180+ desk has no `web/index.html`, so it can't come out without its frontend.
159181- silo has no flake. Its CI deploys all of urbit's `pkg/base-dev`, then
160182 landscape's `desk-dev`, then its own `desk/`, and `flake.nix` builds the
161− same, with landscape at `master`, as the CI takes it, and urbit at
162− `408k-2`, since the CI's tag isn't public. After moving silo's pin, check
163− its `.github/helpers/deploy.sh`.
164−- A desk whose docket names a glob only builds with its glob, which
165− `flake.nix` builds from the app's `ui/`. A glob for a desk whose docket
166− names none fails the build too.
183+ same, with landscape at `master`, as the CI takes it. The CI's urbit tag
184+ isn't public, so `flake.nix` takes `408k-2`, the release of the newest
185+ kernel silo lists; when silo lists a newer one, move `silo-urbit` to its
186+ tag. A few of base-dev's libraries import files the desk lacks, so
187+ deskjam's confirm page warns about them, but silo doesn't use them. silo's
188+ old esbuild names two unused variables at random, so `silo-glob` can differ
189+ by a few bytes from one build to the next, and
190+ `nix build --rebuild .#silo-glob` can fail. The page works the same either
191+ way.
192+- A desk whose docket names a glob, however the docket is laid out, only
193+ builds with its glob, which `flake.nix` builds from the app's `ui/`. A glob
194+ for a desk whose docket names none fails the build too.
195+- A hash in `flake.nix` pins each frontend's npm packages: each glob's
196+ `npmDepsHash`, and the `hash` of harness' `npmDeps`. When moving an app's
197+ pin changes its `package-lock.json`, its build stops with a hash mismatch,
198+ or `npmDepsHash is out of date`. Set that hash to `pkgs.lib.fakeHash`,
199+ build again, and put the hash the error shows after `got:` in its place.
167200
168201## jammer
169202