@@ -10,28 +10,31 @@ files.
11| App | Description | Source | Build |
11| App | Description | Source | Build |
12|---|---|---|---|
12|---|---|---|---|
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` |
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 github:iko-soy/urbit-apps#accountability` |
14−| `%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+| `%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 github:iko-soy/urbit-apps#deskjam` |
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` |
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 and its documents need `%groups`. Installing it takes a few minutes, while Clay builds it. | [mopfel-winrux/urbit-agent-harness](https://github.com/mopfel-winrux/urbit-agent-harness) | `nix build github:iko-soy/urbit-apps#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` |
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 that kiln syncs from another ship, as after `\|install`: not ones installed from a deskjam file, or ones you stop kiln syncing. 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 github:iko-soy/urbit-apps#hits` |
17−| `%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` |
17+| `%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 github:iko-soy/urbit-apps#shelf` |
18−| `%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` |
18+| `%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. Its frontend is a glob: see [Frontends](#frontends). A fork of [arthyn/silo](https://github.com/arthyn/silo). | [iko-soy/silo](https://github.com/iko-soy/silo) | `nix build github:iko-soy/urbit-apps#silo` |
19−
19+| `%vita` | Tracks how your published apps spread: how many ships sync each of your desks, and the daily active users that apps using its `vita-client` library report, with a dashboard for creating and maintaining apps. Its frontend is a glob: see [Frontends](#frontends). A fork of [assemblycapital/vita](https://github.com/assemblycapital/vita), updated for kernel 408. | [iko-soy/vita](https://github.com/iko-soy/vita) | `nix build github:iko-soy/urbit-apps#vita` |
20−Run the build commands in a checkout of this repo, with Nix and flakes
20+
21+The build commands need Nix with flakes enabled, but no clone of this repo:
22+Nix fetches it from GitHub, and each app's source at the version `flake.lock`
21−enabled. If flakes aren't enabled, put
23+pins. If flakes aren't enabled, put
22−`--extra-experimental-features 'nix-command flakes'` after `nix`. Without a
24+`--extra-experimental-features 'nix-command flakes'` after `nix`. In a
23−checkout, give the repo's address instead of `.`, such as
25+checkout of this repo, `.` builds your working copy instead, as in
24−`nix build github:iko-soy/urbit-apps#shelf`. Nix fetches each app's source
26+`nix build .#shelf`.
25−itself, at the version `flake.lock` pins.
27Each build writes `result/<desk>.deskjam`, such as `result/shelf.deskjam`, in
28Each build writes `result/<desk>.deskjam`, such as `result/shelf.deskjam`, in
28place of the last build's `result`. For an app whose web frontend is a glob,
29place of the last build's `result`. For an app whose web frontend is a glob,
29such as hits, it also writes the glob's files next to it, as
30such 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`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+so a deskjam never comes without its glob.
33+`nix build github:iko-soy/urbit-apps#hits-glob`, or `#silo-glob` or
34+`#vita-glob`, builds just a glob. In a checkout,
32−`.#silo-glob` builds just a glob. `nix build .#accountability .#deskjam
35+`nix build .#accountability .#deskjam .#harness .#hits .#shelf .#silo .#vita`
33−.#harness .#hits .#shelf .#silo` builds all six, into `result` and `result-1`
36+builds all seven, in that order, into `result` and `result-1` to `result-6`.
34−to `result-5`.
37+The steps below assume one app's `result`.
36You can install these files on your ship with
39You can install these files on your ship with
37[iko-soy/deskjam](https://github.com/iko-soy/deskjam): see
40[iko-soy/deskjam](https://github.com/iko-soy/deskjam): see
@@ -79,9 +82,10 @@ After that, update deskjam like any other app, as below.
792. Under **upload deskjam**, choose the file, such as `result/shelf.deskjam`,
822. Under **upload deskjam**, choose the file, such as `result/shelf.deskjam`,
80 and click **upload**.
83 and click **upload**.
813. Under **Install it as a new desk**, keep the name and click **next**.
843. Under **Install it as a new desk**, keep the name and click **next**.
85+4. On the confirm page, if the app's frontend is a glob, first click **set**
86+ in the glob box, as [Frontends](#frontends) says. Then tick
82−4. On the confirm page, tick **start its agents after uploading** (for an app
87+ **start its agents after uploading** (for an app without agents, such as
83− without agents, such as silo, **mark it running after uploading**), and
88+ silo, **mark it running after uploading**), and click **confirm**.
855. The status page says whether the app runs.
895. The status page says whether the app runs.
87Once it runs, see the app's README for how to set it up.
91Once it runs, see the app's README for how to set it up.
@@ -90,19 +94,26 @@ Once it runs, see the app's README for how to set it up.
91Apps installed this way don't update on their own. To update one:
95Apps installed this way don't update on their own. To update one:
93−1. Move its pin to the latest commit of its repo, such as with
97+1. Build it again. Nix reuses a copy of this repo it fetched in the last hour,
98+ so add `--refresh` to get the pins it has now:
99+ `nix build --refresh github:iko-soy/urbit-apps#shelf`. To build an app's
100+ newest commit before this repo pins it, add
101+ `--override-input shelf github:iko-soy/shelf`. In a checkout,
94− `nix flake update shelf`, and build it again. `nix flake update` moves
102+ `nix flake update shelf` moves the pin, and `nix flake update` moves every
95− every app, and nixpkgs.
103+ app, and nixpkgs.
962. Upload the new file as above. Under **Update an existing desk**, choose the
1042. Upload the new file as above. Under **Update an existing desk**, choose the
97 app's desk, select **replace it**, and click **next**. Replace makes the
105 app's desk, select **replace it**, and click **next**. Replace makes the
98 desk exactly the upload, so files a new version removed don't linger.
106 desk exactly the upload, so files a new version removed don't linger.
993. The confirm page offers a download of the desk as it is now. Keep it if
1073. The confirm page offers a download of the desk as it is now. Keep it if
100− you might want to go back, then click **confirm**.
108+ you might want to go back. If your ship serves the app's glob, click
109+ **set** in the glob box first. Then click **confirm**.
102Uploading the kept copy with **replace it** puts the old version back. If the
111Uploading the kept copy with **replace it** puts the old version back. If the
103update changed the state an agent keeps, that usually fails, and nothing
112update changed the state an agent keeps, that usually fails, and nothing
104changes. But some agents start afresh from state they can't read, and lose it
113changes. But some agents start afresh from state they can't read, and lose it
105−instead: deskjam's does.
114+instead: deskjam's does. If your ship serves the app's glob, also copy its old
115+`result/<desk>-glob` somewhere before you build the new version, and upload it
116+at `/docket/upload` after putting the old version back.
107If the app came from another ship with `|install`, kiln, the part of your
118If the app came from another ship with `|install`, kiln, the part of your
108ship that installs and updates apps, keeps it in sync with that ship. That
119ship that installs and updates apps, keeps it in sync with that ship. That
@@ -120,18 +131,20 @@ folder is what you upload at `/docket/upload`: choose the app's desk and the
120folder, and click **glob!**. Use a browser other than Safari, which can't
131folder, and click **glob!**. Use a browser other than Safari, which can't
121upload folders.
132upload folders.
123−- silo's docket has `%docket` download its glob from a url, so `silo.deskjam`
134+hits', silo's and vita's dockets have `%docket` get their globs from
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
135+`~donmec-sallud` over Ames, with a placeholder hash. On your ship:
137+1. When you install the deskjam, click **set** in the glob box on the confirm
127− confirm page when you install `hits.deskjam`, so your ship serves the glob
138+ page first, so your ship serves the glob instead. **set** reloads the page
139+ and clears the boxes below it, so tick **start its agents after uploading**
140+ after it, then confirm.
128− instead, and once hits runs, upload `result/hits-glob`. On
141+2. Once the app runs, upload its `result/<desk>-glob`.
129− `~donmec-sallud`, hits' docket already names your ship, so just upload the
143+On `~donmec-sallud`, their dockets already name your ship, so skip **set**,
130− glob. Without its glob, hits runs, but has no frontend.
144+and just upload the glob. Without its glob, an app runs, but has no frontend.
131−- To serve silo's frontend from your own ship too, click **set** the same way
145+deskjam's
132− and upload `result/silo-glob`, as deskjam's
133− [Serving a glob from your ship](https://github.com/iko-soy/deskjam/blob/main/docs/globs.md#serving-a-glob-from-your-ship)
146+[Serving a glob from your ship](https://github.com/iko-soy/deskjam/blob/main/docs/globs.md#serving-a-glob-from-your-ship)
134− says.
147+has the details.
136When you update an app whose glob your ship serves, click **set** in the glob
149When you update an app whose glob your ship serves, click **set** in the glob
137box on the confirm page first, which keeps the glob your ship serves now.
150box on the confirm page first, which keeps the glob your ship serves now.
@@ -163,10 +176,16 @@ has the details, including what to do when an upload goes wrong.
164## How the desks are built
177## How the desks are built
166−- deskjam's, hits' and shelf's own flakes build their desks, so each
179+- deskjam's, hits', shelf's, silo's and vita's own flakes build their desks,
167− `.deskjam` file has the files that repo's own build makes. jammer leaves
180+ so each `.deskjam` file has the files that repo's own build makes. jammer
168− out the files a `|commit` would skip too, such as hits' `LICENSE`, which has
181+ leaves out the files a `|commit` would skip too, such as hits' `LICENSE`,
169− no extension.
182+ which has no extension. silo's and vita's flakes build their globs too, and
183+ this flake takes them as they are, with the nixpkgs those flakes pin: so
184+ `github:iko-soy/urbit-apps#silo-glob` is the same build as
185+ `github:iko-soy/silo#glob`. Their desks
186+ include all of urbit's base-dev, so deskjam's confirm page warns about a
187+ few of its libraries that import files the desks lack, but the apps don't
170- accountability has no flake, and its `desk/` is the whole desk, which
189- accountability has no flake, and its `desk/` is the whole desk, which
171 `flake.nix` packs as it is.
190 `flake.nix` packs as it is.
172- harness' repo builds its desk with `zig build`. It builds `fe/`, its
191- harness' repo builds its desk with `zig build`. It builds `fe/`, its
@@ -175,28 +194,24 @@ has the details, including what to do when an upload goes wrong.
175 grubbery's desk under harness' own. `flake.nix` runs the same `zig build`
194 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
195 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
196 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
197+ other. When a new version of harness pins other commits, change the commit
179− `harness-grubbery` or `harness-tlon` to them. The build also fails if the
198+ in `harness-grubbery`'s or `harness-tlon`'s url in `flake.nix` to the one
199+ the error names: `nix flake update` won't move them. The build also fails
180− desk has no `web/index.html`, so it can't come out without its frontend.
200+ if the desk has no `web/index.html`, so it can't come out without its
181−- silo has no flake. Its CI deploys all of urbit's `pkg/base-dev`, then
201+ frontend. Two of grubbery's libraries in it, `lib/verb.hoon` and
182− landscape's `desk-dev`, then its own `desk/`, and `flake.nix` builds the
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
202+ `lib/xray.hoon`, import files the desk lacks, so deskjam's confirm page
187− deskjam's confirm page warns about them, but silo doesn't use them. silo's
203+ warns about them, but harness doesn't use them.
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
192−- A desk whose docket names a glob, however the docket is laid out, only
204+- A desk whose docket names a glob only builds with its glob, and a glob for
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.
205+ a desk whose docket names none fails the build too. `flake.nix` reads each
206+ docket as the docket mark does, with Hoon's own parser in `urbit eval`, so
207+ this holds however the docket is laid out, and a docket that isn't valid
195−- A hash in `flake.nix` pins each frontend's npm packages: each glob's
209+- A hash in `flake.nix` pins the npm packages of the frontends it builds
196− `npmDepsHash`, and the `hash` of harness' `npmDeps`. When moving an app's
210+ itself: `hits-glob`'s `npmDepsHash`, and the `hash` of harness' `npmDeps`.
211+ silo's and vita's are in their own flakes. When moving an app's pin changes
197− pin changes its `package-lock.json`, its build stops with a hash mismatch,
212+ its `package-lock.json`, its build stops with a hash mismatch, or
198− or `npmDepsHash is out of date`. Set that hash to `pkgs.lib.fakeHash`,
213+ `npmDepsHash is out of date`. Set that hash to `pkgs.lib.fakeHash`, build
199− build again, and put the hash the error shows after `got:` in its place.
214+ again, and put the hash the error shows after `got:` in its place.