@fungi.computer/oyster 0.14.1 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +178 -1552
  2. package/dist/agents.d.ts +8 -0
  3. package/dist/agents.js +6 -0
  4. package/dist/app-builds.d.ts +5 -6
  5. package/dist/app-builds.js +3 -10
  6. package/dist/apps/permissions.js +8 -1
  7. package/dist/auth.d.ts +2 -0
  8. package/dist/auth.js +9 -8
  9. package/dist/boot-host-script.js +1 -1
  10. package/dist/build/candidate-cli.mjs +4 -0
  11. package/dist/catalog-frame.d.ts +0 -1
  12. package/dist/computer.d.ts +5 -0
  13. package/dist/computer.js +1 -0
  14. package/dist/embed-metafiles.js +2 -2
  15. package/dist/embed-scripts.js +3 -3
  16. package/dist/hello-app-script.js +1 -1
  17. package/dist/host-page-assets.js +1 -1
  18. package/dist/host-page.d.ts +5 -1
  19. package/dist/host-page.js +23 -23
  20. package/dist/host.js +6 -1
  21. package/dist/page/app-access.js +23 -1
  22. package/dist/page/app-permissions.js +165 -50
  23. package/dist/page/app-rights.d.ts +8 -0
  24. package/dist/page/app-rights.js +13 -0
  25. package/dist/page/computer-handles.d.ts +15 -0
  26. package/dist/page/computer-handles.js +4 -1
  27. package/dist/page/mount.d.ts +5 -0
  28. package/dist/page/mount.js +4 -0
  29. package/dist/page-script.js +3 -3
  30. package/dist/standalone/agents.js +10 -0
  31. package/dist/standalone/app-set.d.ts +9 -0
  32. package/dist/standalone/app-set.js +43 -0
  33. package/dist/standalone/app-source.js +16 -1
  34. package/dist/standalone/builds.d.ts +2 -2
  35. package/dist/standalone/builds.js +4 -0
  36. package/dist/standalone/cloudflare-account.d.ts +10 -0
  37. package/dist/standalone/cloudflare-account.js +17 -0
  38. package/dist/standalone/computer.d.ts +8 -3
  39. package/dist/standalone/computer.js +26 -3
  40. package/dist/standalone/install-apps-cli.js +1 -1
  41. package/dist/standalone/local-desktop.d.ts +19 -2
  42. package/dist/standalone/local-desktop.js +38 -15
  43. package/dist/standalone/media.d.ts +2 -0
  44. package/dist/standalone/media.js +17 -1
  45. package/dist/standalone/registry.d.ts +4 -1
  46. package/dist/standalone/registry.js +6 -0
  47. package/dist/standalone/sign-in-link.d.ts +1 -1
  48. package/dist/standalone/sign-in-link.js +9 -18
  49. package/dist/standalone/try-cli.d.ts +7 -0
  50. package/dist/standalone/try-cli.js +88 -8
  51. package/dist/starter-agent.d.ts +59 -0
  52. package/dist/starter-agent.js +85 -0
  53. package/docs/api/README.md +744 -88
  54. package/docs/api/agents.md +6 -0
  55. package/docs/api/auth.md +10 -0
  56. package/docs/api/computer.md +4 -0
  57. package/docs/api/page/mount.md +2 -0
  58. package/docs/api/workers-git.md +14 -9
  59. package/docs/api/workers.md +8 -3
  60. package/docs/site/agent-quickstart.mdx +1 -1
  61. package/package.json +34 -50
package/README.md CHANGED
@@ -1,22 +1,23 @@
1
1
  # Oyster (`@fungi.computer/oyster`)
2
2
 
3
- Oyster puts a desktop of Apps on your own Cloudflare account: a git platform,
4
- agents, a terminal, an editor, workflows and image generation, each built from a
5
- git commit on your own Computer.
6
-
7
- The owner can read a build's status at `GET /api/builds/:jobId` and its combined
8
- stdout/stderr at `GET /api/builds/:jobId?log`. The status diagnostic stays
9
- within 200 characters and points to the log. The log returns base64url-encoded
10
- raw bytes; if output exceeds 2 MiB it retains the head and tail and reports
11
- `truncated.droppedBytes`. Both reads use the same owner authorization.
3
+ Oyster is a desktop of Apps you run yourself: a git platform, agents, a
4
+ terminal, an editor, workflows and image generation. People open the Apps in a
5
+ browser, and agents call the same Apps over MCP. Every App is built from an
6
+ exact git commit and runs in its own sandbox with its own database, and you
7
+ choose which version is live.
12
8
 
13
9
  <picture>
14
10
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/desktop-light.png">
15
11
  <img alt="The Tourtois desktop on Oyster with three Apps tiled: Trellis editing the Bonsai checks graph, Bonsai drawing a repository's network of agent forks, and Shed's terminal on the Computer" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/desktop-dark.png">
16
12
  </picture>
17
13
 
18
- Deploy one Worker, run `npx oyster install-apps`, and your Oyster builds seven
19
- Apps on its own Computer and opens on the Tourtois desktop.
14
+ There are three ways in, from least to most code:
15
+
16
+ 1. **Try it** on your computer with one command.
17
+ 2. **Deploy it** to your Cloudflare account. The whole Oyster is a two-line
18
+ Worker.
19
+ 3. **Build your own host** with `createOysterWorker` when you want only part of
20
+ it.
20
21
 
21
22
  ## Quick start: try it on your computer
22
23
 
@@ -26,74 +27,48 @@ No Cloudflare account, Docker or payment. You need Node 24 or newer and Git.
26
27
  npx @fungi.computer/oyster try
27
28
  ```
28
29
 
29
- That creates `./my-oyster`, installs it, starts Oyster at
30
- `http://127.0.0.1:8787`, builds the Oyster desktop (Tourtois) from its public
31
- source, installs a one-page Hello App and opens your browser through a one-time
32
- sign-in link (the key is never put in a URL). You land on the desktop with Hello
33
- in the launcher; the page it opens reads **Hello from my first Oyster App**. The
34
- owner key is saved in `my-oyster/.oyster-owner` and never printed. Press Ctrl-C
35
- to stop, and run the same command again in `my-oyster` to restart. Use
36
- `--port <number>` for another port and `--no-open` to keep the browser closed.
37
- Output is quiet: install and server logs go to `my-oyster/.oyster/`, and
38
- `--verbose` streams them instead. Piped or CI output is plain lines.
39
-
40
- <details>
41
- <summary>What it does under the hood</summary>
42
-
43
- `try` runs these steps (shown for pnpm 11; with npm, skip the
44
- `pnpm-workspace.yaml`). Wrangler is an ordinary dependency; nothing is hidden.
45
-
46
- ```sh
47
- mkdir my-oyster && cd my-oyster
48
- cat > pnpm-workspace.yaml <<'YAML'
49
- allowBuilds:
50
- "@google/genai": false
51
- "@mongodb-js/zstd": false
52
- esbuild: true
53
- exifreader: false
54
- node-liblzma: false
55
- protobufjs: false
56
- workerd: true
57
- YAML
58
- pnpm add @fungi.computer/oyster @fungi.computer/computer react@^19.2.0 react-dom@^19.2.0
59
- pnpm add -D wrangler
60
- cp node_modules/@fungi.computer/oyster/examples/standalone/{worker.ts,wrangler.jsonc} .
61
- export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
62
- echo "$OYSTER_OWNER_KEY" > .oyster-owner
63
- npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
64
- --local-upstream oyster.test --upstream-protocol https \
65
- --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test
66
- ```
67
-
68
- Then it builds Tourtois from `github.com/fungi-computer/tourtois` the same way
69
- (`src/standalone/local-desktop.ts`), and packs a committed one-page
70
- `bundled-html` App with `packRelease` and installs it as `hello` with
71
- `installRelease` (both from `@fungi.computer/oyster/pack`) against
72
- `OYSTER_URL=http://127.0.0.1:8787`; the source is `src/standalone/hello-app.ts`
73
- in this package.
74
-
75
- </details>
76
-
77
- Locally there is no Computer, git storage or Workers AI, so you install your own
78
- App rather than the seven starter Apps below. The
30
+ That creates `./my-oyster`, starts Oyster at `http://127.0.0.1:8787`, builds the
31
+ Tourtois desktop from its public source, installs a one-page Hello App and opens
32
+ your browser through a one-time sign-in link. You land on the desktop with Hello
33
+ in the launcher; the page it opens reads **Hello from my first Oyster App**.
34
+
35
+ Once the desktop is up, `try` keeps building the other starter Apps from their
36
+ public sources in the background, one at a time, and prints a line for each:
37
+ Grove, Prints, Inkcap, Trellis and Bonsai run fully on your computer; Shed
38
+ installs but needs a Computer runtime that a trial does not have. Running `try`
39
+ again leaves installed Apps untouched.
40
+
41
+ The owner key is saved in `my-oyster/.oyster-owner` and never printed. Press
42
+ Ctrl-C to stop, and run the same command again in `my-oyster` to restart.
43
+ `--port <number>` picks another port, `--no-open` keeps the browser closed, and
44
+ `--verbose` streams the install and server logs that otherwise go to
45
+ `my-oyster/.oyster/`.
46
+
47
+ `try` makes an ordinary project, with nothing hidden: Oyster, its Computer,
48
+ React and Wrangler as dependencies, the package's example `worker.ts` and
49
+ `wrangler.jsonc`, and `wrangler dev`. It then builds Tourtois, packs the Hello
50
+ App with `packRelease` and installs it with `installRelease`. The Hello source
51
+ stays in `my-oyster/hello-app` as a git repository you can edit.
52
+
53
+ Locally there is no Computer, git storage or Workers AI, so `try` builds the
54
+ starter Apps on your machine instead of on an Oyster Computer. The
79
55
  [short quick start](https://docs.fungi.computer/oyster-quickstart/) walks the
80
56
  same path; the
81
57
  [agent quick start](https://docs.fungi.computer/oyster/agent-quickstart/) adds
82
- MCP and deployment. For the full desktop, continue to the
83
- [guide to running your own Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/#deploy-it).
58
+ MCP and deployment.
84
59
 
85
60
  ## What you get
86
61
 
87
- `oyster install-apps` installs these Apps. Each one lives in its own repository
88
- under [github.com/fungi-computer](https://github.com/fungi-computer), and each
89
- installed App is also a template your agents can fork and rebuild on the same
90
- Computer.
62
+ Deploying Oyster and running `npx oyster install-apps` installs seven Apps. Each
63
+ lives in its own repository under
64
+ [github.com/fungi-computer](https://github.com/fungi-computer), and each
65
+ installed App is also a template your agents can fork and rebuild.
91
66
 
92
67
  - [Tourtois](https://github.com/fungi-computer/tourtois) is the desktop: a
93
68
  launcher, tiled or floating windows, menus and settings.
94
- - [Bonsai](https://github.com/fungi-computer/bonsai) hosts git repositories on
95
- Cloudflare Artifacts. Each agent pushes to its own fork with ordinary `git`,
96
- and the network graph shows the forks folding back into main.
69
+ - [Bonsai](https://github.com/fungi-computer/bonsai) hosts git repositories.
70
+ Each agent pushes to its own fork with ordinary `git`, and the network graph
71
+ shows the forks folding back into main.
97
72
  - [Grove](https://github.com/fungi-computer/grove) holds conversations with
98
73
  agents that call every installed App as code.
99
74
  - [Shed](https://github.com/fungi-computer/shed) opens a terminal on the
@@ -104,9 +79,6 @@ Computer.
104
79
  - [Prints](https://github.com/fungi-computer/prints) generates images and video
105
80
  with Workers AI.
106
81
 
107
- Stage is not published or included in the 0.3 starter set. It appears as a
108
- glowing ember swarm and directs animated scenes and cards as an agent answers.
109
-
110
82
  <table>
111
83
  <tr>
112
84
  <td width="50%"><img alt="Bonsai's koi-pond repository: a network graph with one lane per agent fork, its three open Changes and the live activity feed" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/bonsai-koi-pond.png"><br><b>Bonsai</b>: a repository three agents build together</td>
@@ -114,369 +86,80 @@ glowing ember swarm and directs animated scenes and cards as an agent answers.
114
86
  </tr>
115
87
  <tr>
116
88
  <td width="50%"><img alt="Trellis editor with the Bonsai checks graph: Workflow input, a Change script node and a Bonsai Checks.report step, between the Palette and the Inspector" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/workflows-editor.png"><br><b>Trellis</b>: a graph of App methods</td>
117
- <td width="50%"><img alt="Inkcap with the koi-pond workspace in the explorer and src/fish.ts open beside README.md" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/inkcap-editor.png"><br><b>Inkcap</b>: the Computer's files</td>
118
- </tr>
119
- <tr>
120
- <td width="50%"><img alt="The Tourtois desktop: Grove's inbox of agent conversations and a launcher for Bonsai, Grove, Inkcap, Prints, Shed and Trellis" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/tourtois-desktop.png"><br><b>Tourtois</b>: the inbox and the launcher</td>
121
89
  <td width="50%"><img alt="Prints: a gallery of five generated images, two koi ponds, a knight dunking a basketball, an elf holding a basketball and a sunrise over water, above the prompt bar" src="https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/prints-gallery.png"><br><b>Prints</b>: images from Workers AI</td>
122
90
  </tr>
123
91
  </table>
124
92
 
125
- Shed is in the desktop picture at the top. Oyster itself is the host underneath:
126
- git through Cloudflare Artifacts, a Computer (a Linux workspace in a Cloudflare
127
- Container) that builds Apps and runs their terminals and files, Agents on
128
- Workers AI, Workflows and media.
129
-
130
93
  ## Deploy to Cloudflare
131
94
 
132
- Deciding what to run?
133
- [Is Oyster for you?](https://docs.fungi.computer/is-oyster-for-you/) compares
134
- agent Computers and App builds with Cloudflare Workers Builds.
135
-
136
- You need:
137
-
138
- - a Cloudflare account on Workers Paid, with Containers, Artifacts, Workers AI,
139
- Workflows and Browser Rendering (now called Browser Run) enabled;
140
- - Docker, which Wrangler uses to build the Computer's container image;
141
- - Node 24, pnpm 11 or newer and Git.
95
+ You need a Cloudflare account on Workers Paid with Containers, Artifacts,
96
+ Workers AI, Workflows and Browser Rendering enabled; Docker, which Wrangler uses
97
+ to build the Computer's image; and Node 24 or newer and Git. Not sure it fits?
98
+ [Is Oyster for you?](https://docs.fungi.computer/is-oyster-for-you/) compares it
99
+ with Cloudflare Workers Builds.
142
100
 
143
- The first install takes about 15 to 20 minutes, mostly building the seven Apps
144
- on the Computer. By default, Oyster builds two Apps at a time. Start a project,
145
- add Oyster, its Computer and Wrangler, and copy the example Worker out of the
146
- package. The local pnpm policy allows esbuild and workerd to install their
147
- native binaries and disables unneeded optional dependency scripts, so a fresh
148
- install exits successfully:
149
-
150
- ```sh
151
- mkdir my-oyster && cd my-oyster
152
- cat > pnpm-workspace.yaml <<'YAML'
153
- allowBuilds:
154
- "@google/genai": false
155
- "@mongodb-js/zstd": false
156
- esbuild: true
157
- exifreader: false
158
- node-liblzma: false
159
- protobufjs: false
160
- workerd: true
161
- YAML
162
- pnpm add @fungi.computer/oyster @fungi.computer/computer react@^19.2.0 react-dom@^19.2.0
163
- pnpm add -D wrangler
164
- cp node_modules/@fungi.computer/oyster/examples/standalone/{worker.ts,wrangler.jsonc} .
165
- ```
166
-
167
- If `pnpm add` reports `ERR_PNPM_IGNORED_BUILDS`, check that the policy file
168
- above exists before installing. If it names a new dependency not listed there,
169
- stop and review that package before allowing its scripts. Do not treat exit 1 as
170
- success.
171
-
172
- `worker.ts` re-exports the whole host:
101
+ The project `try` made is ready to deploy. Its `worker.ts` is the whole Oyster:
173
102
 
174
103
  ```ts title="worker.ts"
175
104
  export * from "@fungi.computer/oyster/standalone";
176
105
  export { default } from "@fungi.computer/oyster/standalone";
177
106
  ```
178
107
 
179
- `wrangler.jsonc` names the Worker `oyster`, its Release bucket `oyster-releases`
180
- and its Artifacts namespace `oyster`, and runs the Computer from
181
- `node_modules/@fungi.computer/computer/Dockerfile`. Its
182
- `"browser": { "binding": "BROWSER" }` enables Cloudflare Browser Rendering for
183
- the zero-grant UI boot check and for Agents' browser tool. Without the binding
184
- the UI of a Release is reported `not_checked` with
185
- `code: "boot_browser_binding_missing"`; the install still proceeds.
186
-
187
- Create the bucket and deploy. Your Worker's address is
188
- `https://oyster.<your-subdomain>.workers.dev`; your workers.dev subdomain is on
189
- the Workers & Pages overview in the Cloudflare dashboard.
108
+ Its `wrangler.jsonc` declares every binding: the `oyster-releases` R2 bucket,
109
+ the `oyster` Artifacts namespace, the Computer's container from
110
+ `@fungi.computer/computer`, and Browser Rendering for UI boot checks and the
111
+ Agents' browser. From `my-oyster`:
190
112
 
191
113
  ```sh
192
114
  npx wrangler login
193
115
  npx wrangler r2 bucket create oyster-releases
194
116
  export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
195
117
  npx wrangler deploy --var OYSTER_ORIGIN:$OYSTER_URL
196
- ```
197
-
198
- Set `OYSTER_ORIGIN` in `wrangler.jsonc` instead if you deploy again later; every
199
- deploy replaces the Worker's variables. If you rename the Worker's `name` in
200
- `wrangler.jsonc`, update `OYSTER_ORIGIN` to that Worker's URL at the same time.
201
-
202
- ### API-token permissions and teardown
203
-
204
- For an API token instead of `wrangler login`, load `CLOUDFLARE_API_TOKEN` into
205
- your shell without committing it. Set `CLOUDFLARE_ACCOUNT_ID` (or `account_id`
206
- in `wrangler.jsonc`) explicitly, and skip the login command. Use Wrangler
207
- 4.135.0 or newer; record `npx wrangler --version` for deployment and teardown.
208
-
209
- The [Cloudflare API specification](https://github.com/cloudflare/api-schemas)
210
- names these account-scoped permission groups for the deployment and resource
211
- deletion operations:
212
-
213
- | Permission group | Used for |
214
- | ------------------------ | ----------------------------------------------------------- |
215
- | Workers Scripts Write | Deploy, secrets, Worker deletion and Workflow deletion |
216
- | Workers R2 Storage Write | Release bucket creation, object cleanup and bucket deletion |
217
- | Workers Containers Write | Computer container application management |
218
- | Artifacts Edit | Artifacts namespace and repository management |
219
-
220
- Browser Rendering through the Workers `BROWSER` binding
221
- [needs no additional API-token permission](https://developers.cloudflare.com/browser-run/quick-actions/).
222
- The separate Browser Rendering Write permission is for its REST API, which this
223
- quick start does not use. Workers Paid entitlement is still required.
224
-
225
- For stream-rehearsal diagnostics, include **Browser Rendering (Read)** in the
226
- account-scoped token checklist: it permits REST session inspection, separate
227
- from the `BROWSER` binding's boot operation. Use the documented
228
- `/browser-rendering/devtools/session` list and `devtools/session/{session_id}`
229
- details operations; a session's `endTime`, not its connection end time, reports
230
- closure. A plain 404 from another route does not establish a missing permission.
231
- If inspection is unavailable, record **UNAVAILABLE**, not confirmed cleanup. Do
232
- not broaden an existing token automatically.
233
-
234
- With an explicit account ID, user/account discovery is unnecessary. Do not add
235
- Workers KV Storage Read, User Details Read or Memberships Read just for that
236
- discovery. Wrangler 4.135.0 treats denied legacy-Sites KV inspection during
237
- `wrangler delete` as a warning, not a reason to broaden this token. AI Gateway
238
- Read/Edit permissions are not needed for this deploy or a teardown before any
239
- media ran; inspect that additional resource if media has created a gateway.
240
-
241
- `npx wrangler delete` deletes the Worker, not the entire Oyster. For a throwaway
242
- deployment, also empty and delete the Release bucket, delete the Computer's
243
- container application, delete the Workflow, and delete the Artifacts
244
- repositories and namespace. Use the configured resource names and confirm each
245
- is gone through Cloudflare's dashboard or API. Capture teardown errors and the
246
- Wrangler version rather than silently adding unrelated token permissions.
247
-
248
- ### Upgrading Oyster
249
-
250
- Oyster's version is not Fungi's. Find the Oyster and Computer versions for your
251
- Fungi release on the
252
- [Open source page](https://docs.fungi.computer/reference/packages/#package-versions-in-each-fungi-release),
253
- then run the upgrade command in
254
- [Upgrade Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/#upgrade-oyster)
255
- in your Oyster project, with the same pnpm and store that installed it.
256
-
257
- Redeploy with the same `npx wrangler deploy` command you deployed with, then run
258
- `npx oyster install-apps`. If pnpm stops with `ERR_PNPM_UNEXPECTED_STORE`, rerun
259
- the `pnpm add` with `--store-dir` set to the store the error says the project is
260
- linked from.
261
-
262
- ### Upgrading to owner-only Oyster
263
-
264
- Upgrading to 0.7.0 resets the installed Apps when the registry contains the
265
- pre-owner-only `visibility`, `approvedAnonymousMethods` or `anonymousApproval`
266
- fields. This clears all installation rows and their installation command journal
267
- once, renews the store incarnation, and permanently records the reset time and
268
- row count. It does not uninstall Apps through their storage-purging delete path.
269
- Agents, Sessions, files, keys, source and release data, tenancy, approval
270
- records and Computer state are retained.
271
-
272
- While no App is enabled, Oyster Home shows:
273
-
274
- > This update reset your installed Apps. Reinstall them with npx oyster
275
- > install-apps.
276
-
277
- Run `npx oyster install-apps` to reinstall. The notice disappears when an App is
278
- enabled; the audit fact remains. This is not a compatibility reader or a reset
279
- on arbitrary corruption. The separate pre-0.3 refusal below is unchanged.
280
-
281
- Same-ID App settings: kept and back after reinstall; backend SQLite: kept but
282
- not reachable.
283
-
284
- Each installed App's own backend database (for example saved Notes) stays in
285
- storage but is no longer reachable; reinstalling creates a new App Instance that
286
- starts empty. There is no recovery for App backend data in 0.7.0; reinstalling
287
- with `npx oyster install-apps` restores the Apps and their same-ID App settings,
288
- and Agents, Sessions, files and keys are retained.
289
-
290
- These are different stores. Backend SQLite belongs to the Instance's `app`
291
- facet. Host `APP_STORAGE` settings instead belong to the installation address
292
- plus App ID, key, scope and member membership version; the starter installer
293
- reuses the same installation IDs, so the same App reconnects to those settings.
294
- There is no automatic backend-data reattachment or change to either keying
295
- scheme. Files on Computers and Agent/Session data have their own retained
296
- owners.
297
-
298
- ### Upgrading from Oyster 0.2 or earlier
299
-
300
- Oyster 0.3 does not read data created by Oyster 0.1 or 0.2, and it does not
301
- convert it. An Oyster deployed on 0.2 and redeployed on 0.3 answers every
302
- request with `409` and `{"error": "store_from_older_oyster", ...}` (a short
303
- explanation page in a browser), and `oyster install-apps` prints the same
304
- message. Old data is left untouched, so redeploying 0.2.x brings the Oyster back
305
- exactly as it was.
306
-
307
- To move to 0.3, start from a fresh store. The smallest way is to deploy under
308
- new names, leaving the old Oyster in place until you no longer need it. In
309
- `wrangler.jsonc`, rename `name`, both `bucket_name` values,
310
- `artifacts.namespace` and every `workflows[].name`; create the new release
311
- bucket; then run the quick start again. To reuse the names instead, tear the old
312
- Oyster down as in the teardown steps above (delete the Worker, which deletes its
313
- Durable Object data; empty and delete the release bucket; delete the Computer's
314
- container application, the Workflow, and the Artifacts repositories and
315
- namespace), then deploy 0.3 and reinstall the Apps. Data in the old Oyster, such
316
- as Apps' stored data, is not carried over.
317
-
318
- ### Set the Oyster owner key
319
-
320
- Choose an owner key (separate from the Cloudflare API token) and store it as a
321
- secret:
322
-
323
- ```sh
324
- export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
325
- printf '%s' "$OYSTER_OWNER_KEY" | npx wrangler secret put OYSTER_OWNER_KEY
326
- ```
327
-
328
- ### Set the credential key (to bring your own model keys)
329
-
330
- Model API keys you add in Settings are sealed on your Oyster under a 32-byte
331
- credential key held as a host secret. Generate it at install; it is never in the
332
- repository, storage or logs. Without it, adding a model key is refused.
333
-
334
- ```sh
118
+ printf '%s' "$(cat .oyster-owner)" | npx wrangler secret put OYSTER_OWNER_KEY
335
119
  openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' |
336
120
  npx wrangler secret put OYSTER_CREDENTIAL_KEY
337
- ```
338
-
339
- Keep a copy: losing it makes the sealed keys unreadable, and you re-add them.
340
-
341
- ### Install the starter Apps
342
-
343
- ```sh
121
+ export OYSTER_OWNER_KEY=$(cat .oyster-owner)
344
122
  npx oyster install-apps
345
123
  ```
346
124
 
347
- The installer clones each App's repository, seeds it on your Oyster with
348
- `git push`, and builds the Apps on your Computer, Tourtois first, installing
349
- each as its build succeeds. It prints a line per step and then where the time
350
- went:
351
-
352
- ```
353
- tourtois source recorded at git:…
354
- …
355
- Building tourtois on the Computer (build_…)
356
- Installed tourtois from its build build_…
357
- Building bonsai on the Computer (build_…)
358
- …
359
- Installed grove from its build build_…
360
-
361
- App fetch seed queue build clone deps compile upload install
362
- tourtois …
363
- …
364
- Installed 7 Apps in …. Open https://oyster.<your-subdomain>.workers.dev/ to use Tourtois and the installed Apps.
365
- ```
125
+ Your workers.dev subdomain is on the Workers & Pages overview in the Cloudflare
126
+ dashboard. `OYSTER_CREDENTIAL_KEY` seals the model API keys you add in Settings;
127
+ keep a copy, because losing it makes those keys unreadable. Set `OYSTER_ORIGIN`
128
+ in `wrangler.jsonc` if you deploy again later, since every deploy replaces the
129
+ Worker's variables.
366
130
 
367
- Open `$OYSTER_URL/login` and sign in with the owner key: your Oyster opens on
368
- the Tourtois desktop with all seven Apps, as in the pictures above.
131
+ The first `install-apps` takes about 15 to 20 minutes, mostly building the seven
132
+ Apps on your Computer, two at a time. It prints a line per step and a timing
133
+ table, ending with `Installed 7 Apps`. Open `$OYSTER_URL/login`, sign in with
134
+ the owner key, and your Oyster opens on the Tourtois desktop. Run `install-apps`
135
+ again to update the Apps; a replaced Release keeps each App's data.
369
136
 
370
- Run `install-apps` again to update them; a replaced Release keeps each App's
371
- data. `--ref` picks a branch or tag of the App repositories, `--repositories`
372
- another host for them, and `--timings <file>` writes the timing table as JSON.
373
- Builds run two at a time on the example's `standard-4` Computer (12 GiB).
374
- `--concurrency 1` runs them one at a time and `--concurrency 3` three at once.
137
+ Starting without `try`, deploying with an API token, upgrading, tearing down and
138
+ the celld trial are in the [API reference](docs/api/README.md) under "Deploy and
139
+ operate", and in the
140
+ [guide to running your own Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/).
375
141
 
376
- ### Git, keys and MCP
142
+ ## Connect your agents
377
143
 
378
144
  People and agents `clone`, `fetch` and `push` App repositories with ordinary
379
- `git` at `/git/<installation>/<repo>.git`. Give each agent its own key; Oyster
380
- shows each key once:
145
+ `git` at `/git/<installation>/<repo>.git`, and call every installed App through
146
+ one MCP endpoint at `/mcp`. Give each agent its own key; Oyster shows it once:
381
147
 
382
148
  ```sh
383
149
  curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
384
150
  -H 'content-type: application/json' \
385
151
  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
386
152
  $OYSTER_URL/api/keys
387
- ```
388
-
389
- The answer's `plaintext` field, starting `oyk_`, signs in to `git` and to
390
- `/mcp`. That key can read and write every App on this Oyster, including Apps
391
- installed later, without asking each time; anyone holding it can act as the
392
- owner in those Apps, and revoking it stops it immediately.
393
-
394
- Any MCP client can call every installed App with a key. For Claude Code:
395
-
396
- ```sh
397
153
  claude mcp add --transport http oyster "$OYSTER_URL/mcp" \
398
- --header "Authorization: Bearer <the agent's key>"
154
+ --header "Authorization: Bearer <the oyk_ key from the answer>"
399
155
  ```
400
156
 
401
- ## Part of Fungi
402
-
403
- [Fungi](https://fungi.computer/) runs AI Agents on their own Computers, inside
404
- Teams that share Agents, Computers, Apps and a bill. Oyster is its App host,
405
- released on its own, and it is built from 21 more Fungi packages released with
406
- it. Each one is MIT-licensed, has its own repository at
407
- `github.com/fungi-computer/<name>`, installs from npm as
408
- `@fungi.computer/<name>`, and works without the rest. Installing Oyster brings
409
- in the ones it runs on.
410
-
411
- Apps and hosting:
412
-
413
- - [Agar](https://github.com/fungi-computer/agar): the App contract. Typed
414
- backend methods, host capabilities and the connection between an App's
415
- frontend and its host.
416
- - [Puffball](https://github.com/fungi-computer/puffball): a catalog of web Apps
417
- and their immutable Releases, which serves only promoted Releases and checks
418
- every artifact against its recorded digest.
419
- - [Gills](https://github.com/fungi-computer/gills): compact plain-text App views
420
- shared by browser and terminal hosts.
421
- - [Whistle](https://github.com/fungi-computer/whistle): one command definition
422
- becomes key bindings, a command palette, slash commands, help, a menu and an
423
- agent tool, all running through one typed `execute` door.
424
-
425
- Agents and tools:
426
-
427
- - [Shiitake](https://github.com/fungi-computer/shiitake): durable Agent
428
- conversations. A Session holds accepted work, messages and observations; the
429
- host supplies storage, models and tools.
430
- - [Mule](https://github.com/fungi-computer/mule): runs Pi's model and tool loop
431
- inside Effect as an awaited, cancellable run.
432
- - [Mycelium](https://github.com/fungi-computer/mycelium): gives an Agent typed
433
- operations through one `execute` tool, with a capability snapshot acquired and
434
- released per run.
435
- - [Knapsack](https://github.com/fungi-computer/knapsack): connects an Agent to
436
- Computers, files and remote MCP servers as Mycelium capability sources.
437
- - [Forage](https://github.com/fungi-computer/forage): lists, searches and
438
- describes a catalog of operations, so a caller or a model finds the right one.
439
- - [BirdDog](https://github.com/fungi-computer/bird-dog): durable mail between
440
- agent sessions, with replies retried from an outbox until they are accepted.
441
-
442
- Durable work, git and keys:
443
-
444
- - [Watchdog](https://github.com/fungi-computer/watchdog): a small durable job
445
- engine on SQLite, D1 or PostgreSQL. Each job settles with exactly one recorded
446
- outcome, even across restarts.
447
- - [Carrier](https://github.com/fungi-computer/carrier): durable email delivery
448
- whose receipts record only what the provider said, and ordered envelopes
449
- between Durable Objects.
450
- - [Burrow](https://github.com/fungi-computer/burrow): the repository owner for
451
- Cloudflare Artifacts, serving only Git's smart-HTTP operations and never
452
- returning a credential.
453
- - [Ear Tag](https://github.com/fungi-computer/ear-tag): bearer keys and their
454
- hashes, a typed grant vocabulary, and a tenant-scoped key store with
455
- revocation, expiry and a per-key rate limit.
456
- - [Cairn](https://github.com/fungi-computer/cairn): typed, opaque identifiers,
457
- temporary keys and candidate word names, with their parsers.
458
-
459
- Interface:
157
+ Each App's methods appear as `env.<APP>` in one `execute` tool, for example
158
+ `env.BONSAI.repos.list({})`. This key can read and write every App, including
159
+ Apps installed later, without asking each time. Anyone holding it can act as the
160
+ owner in those Apps, and revoking it stops it at once.
460
161
 
461
- - [Stipe](https://github.com/fungi-computer/stipe): a CSS-first theme layer for
462
- Tailwind CSS v4 and daisyUI 5, with spacing, fonts and material tokens.
463
- - [Caps](https://github.com/fungi-computer/caps): accessible React primitives
464
- and blocks, from buttons and dialogs to a chat composer and window frames,
465
- themed by Stipe.
466
- - [Maosaico](https://github.com/fungi-computer/maosaico): arranges React panes
467
- inside a measured container, with floating frames and optional tiling.
468
- - [Sigils](https://github.com/fungi-computer/sigils): Fungi's decorative SVG
469
- marks and their gallery.
470
- - [Sprite](https://github.com/fungi-computer/sprite): shows an animated
471
- character through a renderer the host installs.
472
- - [Sprite Zdog](https://github.com/fungi-computer/sprite-zdog): a Canvas
473
- renderer for Zdog characters, with built-in characters and authoring tools for
474
- Sprite.
475
-
476
- ## Hand this to your agent
477
-
478
- Paste this prompt into a coding agent (Claude Code, Codex or any other) to have
479
- it set up a local Oyster, install an App, connect over MCP and deploy:
162
+ To have a coding agent set up Oyster for you, paste this prompt:
480
163
 
481
164
  ```text
482
165
  Set up Oyster for me. Install it from npm as @fungi.computer/oyster and follow
@@ -486,1191 +169,134 @@ expected output, and use the "If it fails" notes before improvising. Stop and
486
169
  ask me before step 7 (deploy).
487
170
  ```
488
171
 
489
- The guide ships in the package as `docs/site/agent-quickstart.mdx`. It needs
490
- Node 24, pnpm and Git; a Cloudflare account matters only for the deploy step.
172
+ ## Build your own host
491
173
 
492
- ## Why Oyster
174
+ `@fungi.computer/oyster/workers` is the layer under the whole Oyster: one owner,
175
+ Apps installed from Releases, each App's backend in its own Durable Object with
176
+ SQLite, and the MCP endpoint. It has no git, Computer, Agents or Workflows.
493
177
 
494
- **Apps are Releases with provenance.** `packRelease` builds an App from one
495
- commit and records it as `sourceRevision: git:<sha>`. Every artifact is
496
- addressed by its SHA-256 digest, and Oyster verifies each digest before it
497
- installs or replaces a Release. Replacing a Release keeps the App's data;
498
- deleting it purges the data and leaves a tombstone.
178
+ ```ts title="worker.ts"
179
+ import { createOysterWorker } from "@fungi.computer/oyster/workers";
180
+
181
+ export {
182
+ OysterBinding,
183
+ OysterInstallationExecutor,
184
+ OysterInstance,
185
+ OysterMcp,
186
+ OysterRegistry,
187
+ } from "@fungi.computer/oyster/workers";
188
+
189
+ export default createOysterWorker({
190
+ guestLimits: { cpuMs: 250, subRequests: 10 },
191
+ });
192
+ ```
499
193
 
500
- **Every App is isolated.** An App's backend loads through a Worker Loader into
501
- its own Durable Object facet with its own SQLite database. It has no ambient
502
- network access. It receives only the bindings its Release declares (`GIT`,
503
- `EVENTS`, Computer, agent, workflow, media), and Oyster checks that declaration
504
- again on every request. App pages are served with a deny-by-default Content
505
- Security Policy inside a sandboxed frame.
194
+ Its Wrangler config needs a `LOADER` Worker Loader, a `RELEASES` R2 bucket, the
195
+ `REGISTRY`, `INSTANCES` and `MCP` Durable Objects (SQLite classes
196
+ `OysterRegistry`, `OysterInstance` and `OysterMcp`), and the `OYSTER_OWNER_KEY`
197
+ and `OYSTER_ORIGIN` variables. `guestLimits` is optional; without it each App
198
+ call gets 1,000 ms of CPU and 50 subrequests.
506
199
 
507
- **Git is a binding.** An App that declares `git.repository` gets `env.GIT`:
508
- create, fork, log, read and merge on Cloudflare Artifacts, scoped to its
509
- installation. People and agents push with ordinary `git` through Oyster's git
510
- door using their own keys; the host keeps every provider credential. Each
511
- accepted push reaches the App's `onGitPush` handler and can start a Workflow or
512
- a signed webhook.
200
+ Install an App Release that `packRelease` produced with the `oyster` command:
513
201
 
514
- **Agents are first-class callers.** `POST /mcp` serves one MCP endpoint for the
515
- whole Oyster. Every installed App's methods appear as typed `env.<APP>` modules
516
- that an agent discovers and calls from code; a dotted method is a nested
517
- property, e.g. `env.BONSAI.repos.list({})`. Writes need explicit approval. Each
518
- agent has its own key, so every push and call is attributed.
202
+ ```sh
203
+ oyster install ./notes-release --installation-id notes
204
+ ```
519
205
 
520
- **Workflows compose Apps.** Trellis stores each graph in git, so a commit is a
521
- version. Each graph compiles to a plan with a digest and runs on Cloudflare
522
- Workflows. Steps call App methods and can run a sandboxed Code node or a step in
523
- a Computer.
206
+ When you need more, add one layer at a time:
524
207
 
525
- **Computers are ordinary capabilities.** A Computer is a durable workspace with
526
- a Container backing. Shed opens its terminal, Inkcap edits its files and port
527
- previews serve what it runs on signed hostnames. Apps reach it only through the
528
- `computer.*` capability they declare.
208
+ - `@fungi.computer/oyster/workers-git`: `oysterGitRoot` adds the git door, keys,
209
+ webhooks and Agents.
210
+ - `@fungi.computer/oyster/pack`: `packRelease` and `installRelease` build an App
211
+ from an exact commit and install it over HTTP.
212
+ - `@fungi.computer/oyster/host`: `createOyster(host)` is the same server over
213
+ your own adapters, for a host that is not a Worker.
529
214
 
530
- **The desktop is a trusted shell.** Tourtois is installed like any other
531
- Release, but your Oyster renders its home installation as the top-level page,
532
- with every permission you have as owner. Each App it opens still runs in its own
533
- sandboxed frame inside that App's window. Pick a shell you trust: it can do
534
- anything you can.
215
+ The [API reference](docs/api/README.md) explains each layer and the parts they
216
+ are made of.
535
217
 
536
- ## Architecture
218
+ ## How it works
537
219
 
538
- An Oyster is one Worker. Every App installed on it is an immutable Release built
539
- from an exact git commit. Its UI runs in a sandboxed frame, its backend runs in
540
- its own Durable Object with its own SQLite, and it receives only the bindings it
541
- declares. Agents reach every installed App through one MCP endpoint. The same
542
- Worker runs on Cloudflare Workers and on celld, a Workers-compatible runtime you
543
- can host yourself.
220
+ | Piece | Owns |
221
+ | ----------------- | ----------------------------------------------------------------------------------------- |
222
+ | Router | One declared route table: sign-in, App pages and methods, owner routes, `/mcp`. |
223
+ | `OysterRegistry` | The installation list: which Release each installation runs. |
224
+ | R2 | Release artifacts, stored by their SHA-256 digest and verified before install. |
225
+ | App Instance | One Durable Object per installation: lifecycle, owner state and the backend facet. |
226
+ | Backend facet | The App's own code and SQLite database, loaded through the Worker Loader. |
227
+ | git door | Smart-HTTP `clone`, `fetch` and `push`, admitted per key and forwarded to Artifacts. |
228
+ | Tourtois | The trusted shell: launcher, windows, menus and settings, rendered as the top-level page. |
229
+ | Platform bindings | Workflows, Computers, Agents and Workers AI, offered only to Apps that declare them. |
544
230
 
545
231
  ![Oyster architecture: one Worker routes browsers, git clients and MCP agents to a registry, per-App Durable Objects, the git door and the Tourtois home, over R2, Artifacts and platform bindings](https://raw.githubusercontent.com/fungi-computer/oyster/main/docs/media/architecture.png)
546
232
 
547
- | Piece | Owns |
548
- | ----------------- | ---------------------------------------------------------------------------------------------------- |
549
- | Router | One declared route table (`authorization.ts`): sign-in, App pages and methods, owner routes, `/mcp`. |
550
- | `OysterRegistry` | The installation list: which Release each installation runs. |
551
- | R2 | Release artifacts, stored by digest. |
552
- | App Instance | One Durable Object per installation: lifecycle, owner state and the backend facet. |
553
- | Backend facet | The App's own code and SQLite database, loaded through the Worker Loader. |
554
- | git door | Smart-HTTP `clone`, `fetch` and `push`, admitted per key and forwarded to Artifacts. |
555
- | Tourtois | The trusted shell: launcher, windows, menus and settings, rendered as the top-level page. |
556
- | Platform bindings | Workflows, Computers, Agents and Workers AI, offered only to Apps that declare them. |
557
-
558
- The diagram source is
559
- [`docs/media/architecture.mmd`](https://github.com/fungi-computer/oyster/blob/main/docs/media/architecture.mmd).
233
+ An App's UI runs in a sandboxed frame under a deny-by-default Content Security
234
+ Policy. Its backend has no ambient network access and receives only the bindings
235
+ its Release declares, checked again on every request. Agent writes need
236
+ approval, and each agent's own key attributes every push and call. Oyster is
237
+ owner-only: a browser signs in only with the owner key, and named keys sign in
238
+ only by header, for MCP, git and the API. The same Worker runs on Cloudflare
239
+ Workers and on celld, a Workers-compatible runtime you can host yourself.
560
240
 
561
- ## Install or set up
241
+ ## Install
562
242
 
563
243
  ```sh
564
- pnpm add @fungi.computer/oyster
244
+ npm install @fungi.computer/oyster react react-dom
565
245
  ```
566
246
 
567
247
  Oyster is ESM only and runs on Node 24 or newer, Cloudflare Workers and celld.
568
248
  React and React DOM 18.3 or 19.2 are peer dependencies; the host renders its
569
- pages with them. Wrangler is an optional peer dependency: add it as a dev
570
- dependency to run or deploy the example Workers, which ship in the package under
571
- `examples/`. The generated [API reference](docs/api/README.md) ships in the
572
- package too.
573
-
574
- Oyster's runtime dependencies are other Fungi packages, among them
575
- [Agar](https://github.com/fungi-computer/agar) for the App contract,
576
- [Puffball](https://github.com/fungi-computer/puffball) for Releases and
577
- [Mycelium](https://github.com/fungi-computer/mycelium) for the MCP `execute`
578
- door. "Part of Fungi" above lists them all.
579
-
580
- ## Run your own Oyster
581
-
582
- `@fungi.computer/oyster/standalone` is the whole host the quick start deploys:
583
- the git root below plus tenancy, a Computer (`ComputerDO`, a Cloudflare
584
- Container or an on-box VM), Agents on Workers AI composed from stock
585
- [Shiitake](https://github.com/fungi-computer/shiitake) Durable Objects,
586
- Workflows, media, and the owner routes that seed App templates and build them on
587
- the Computer. `examples/standalone/wrangler.jsonc` declares every binding it
588
- uses. Set the owner key as a secret (`OYSTER_OWNER_KEY`, 24+ characters) and
589
- deploy with `wrangler deploy`. Sign in at `/login`.
590
-
591
- Oyster is owner-only. A browser signs in only with the owner key, through
592
- `/login` and its `SameSite=Strict` session cookie. Named keys sign in only by
593
- header (`Authorization`), for MCP, Git and the API; no cookie admits a named
594
- key. Anonymous requests reach only `/login`, `robots.txt`, digest-pinned shell
595
- and App UI bytes, and the website chat described next.
596
-
597
- ### Website chat on a separate site
598
-
599
- Owner-only means only the owner signs in to Oyster; it does not stop you from
600
- putting an Agent on a public website. In Settings, choose Channels, then Add
601
- website: pick the Agent, give the address of your site and a brief, and paste
602
- the script tag Oyster shows you into that site:
603
-
604
- ```html
605
- <script
606
- src="https://your-oyster.example/embed/v1.js"
607
- data-site="site_pk_…"
608
- data-theme="auto"
609
- async
610
- ></script>
611
- ```
612
-
613
- Visitors are anonymous channel parties of that one Agent, never Oyster
614
- principals, keys or App callers. They talk to the Agent itself, with its own
615
- tools and permissions and the persona you wrote added to its instructions; they
616
- cannot sign in to Oyster or reach your account. Each site has its own key, a
617
- list of allowed origins, rate limits per visitor and per network address, and a
618
- pause switch; a new site key stops the old code at once. The same page can
619
- require a Cloudflare Turnstile check before a visitor can chat, and shows the
620
- conversations so you can read what visitors said.
621
-
622
- The surface is closed until you set two host secrets, each at least 32 bytes:
623
- `OYSTER_WEBSITE_PROOF_KEY` signs a visitor's identity between the public edge
624
- and the website Agent, and `OYSTER_WEBSITE_ADDRESS_KEY` salts the hashed network
625
- address used for rate limits. For Turnstile, set `TURNSTILE_SITE_KEY` and
626
- `TURNSTILE_SECRET_KEY` (or `TURNSTILE=off` for local use over `http`).
627
-
628
- The celld example is a limited trial, not the full Cloudflare setup above. It
629
- requires access to Fungi's private celld fork. Use
630
- `examples/standalone/wrangler.celld.jsonc` beside `worker.ts`, not the
631
- Cloudflare-only config. Oyster `0.6.0` includes both files under
632
- `examples/standalone` in the installed package.
633
-
634
- The layers it is built from stay exported for hosts that compose their own:
635
- `@fungi.computer/oyster/turnstile` owns Cloudflare challenge configuration and
636
- token verification. Hosts supply their origin, verification timeout and safe
637
- error reporter; they retain their own challenged routes and HTTP responses.
638
- Configuration keeps the explicit `TURNSTILE=off` opt-out and fails closed on
639
- HTTPS hosts without both keys. Hub retains its five-second verification policy.
640
-
641
- Other host building blocks: `@fungi.computer/oyster/workers` (Releases,
642
- Instances, MCP and App storage) and `@fungi.computer/oyster/workers-git` (the
643
- git door), with `oysterAppMethods` supplying the installed App catalog to an
644
- Agent runtime.
645
-
646
- Pack and install an App with `@fungi.computer/oyster/pack`: `packRelease` turns
647
- an exact Git commit and a canonical build recipe into a Release with immutable
648
- artifacts, and `installRelease` uploads it. Each installed App gets:
649
-
650
- - its UI at `/apps/<installation>/`, in a sandboxed frame connected through
651
- Agar's `app.backend` capability;
652
- - its methods at `POST /apps/<installation>/methods/<name>` (JSON in and out);
653
- - its own SQLite state in its Instance's `app` facet.
654
-
655
- `createOyster(host)` from `@fungi.computer/oyster/host` is the same server over
656
- your own adapters (`auth`, `artifacts`, `installations`, `instances`, `mcp`,
657
- `capabilities`).
658
-
659
- ### Add Git to your host
660
-
661
- Git is one optional field of the typed host: `host.git`. When it is present,
662
- `createOyster` mounts the git door at `/git/<installation>/<repo>.git`, and
663
- people and agents `clone`, `fetch` and `push` with ordinary git. Nothing else in
664
- the host changes.
665
-
666
- There are two ways to get it:
667
-
668
- - **Use one Git root.** `oysterGitRoot(options)` from
669
- `@fungi.computer/oyster/workers-git` is the whole composition: the git door
670
- plus tenancy, Agents and their owner-only approval routes, workspace and
671
- capability slots, the page script and the home App. Its `hostFor(env, scope)`
672
- is the only way a tenant host is built. Pass the root to
673
- `createOysterGitWorker` for HTTP and to `createOysterGitMcpOwner` for MCP, and
674
- return `root.hostFor(this.env, scope)` from your `OysterGitInstance` subclass,
675
- so HTTP, MCP and background wakes share one composition. `tenancy` is
676
- required; a single-owner root passes `ownerOrKeyTenancy`, so the owner key and
677
- named keys sign git in. `@fungi.computer/oyster/standalone` is a real
678
- multi-door caller. Its `wrangler.jsonc` adds the `ARTIFACTS` binding and the
679
- `KEYS` and `WEBHOOKS` Durable Objects.
680
- - **Set `host.git` on your own host.** Keep your own `createOyster(host)`
681
- composition and set `git: oysterWorkerGit(env, { scope })` and
682
- `ownerRoutes: gitAdminRoutes(env, scope)` for `/api/keys` and `/api/webhooks`,
683
- with the tenant `scope` your host selected.
684
-
685
- The git root, from Workers:
686
-
687
- ```ts title="worker.ts"
688
- import type { TenantScope } from "@fungi.computer/oyster/tenant";
689
- import {
690
- createOysterGitMcpOwner,
691
- createOysterGitWorker,
692
- OysterGitInstance,
693
- oysterGitRoot,
694
- ownerOrKeyTenancy,
695
- type OysterGitWorkerEnv,
696
- } from "@fungi.computer/oyster/workers-git";
697
-
698
- const root = oysterGitRoot<OysterGitWorkerEnv>({ tenancy: ownerOrKeyTenancy });
699
-
700
- export class OysterMcp extends createOysterGitMcpOwner(root) {}
701
-
702
- export class OysterInstance extends OysterGitInstance {
703
- protected hostFor(scope: TenantScope) {
704
- return root.hostFor(this.env, scope);
705
- }
706
- }
707
-
708
- export default createOysterGitWorker(root);
709
- ```
710
-
711
- A host also exports the Durable Objects and the git `OysterBinding` entrypoint,
712
- whose table also serves `env.GIT` and `env.EVENTS`. The package's
713
- `test:git-door` check runs that root (`test/git-root.fixture.ts`) on workerd
714
- against real bare repositories: the owner pushes with `git`, a named agent key's
715
- push is refused by the App's policy with Git's own `ng` report, both keys clone,
716
- and the accepted push reaches the App's `onGitPush`.
717
-
718
- Each layer owns one decision:
719
-
720
- ```mermaid
721
- flowchart LR
722
- client["git client<br/>clone · fetch · push"]
723
- auth["Authentication<br/>owner key · named key<br/>Workflow Git pass header"]
724
- admission["Git admission<br/>enabled installation · git.repository<br/>tenant scope · Workflow branch grant"]
725
- policy["App push policy<br/>authorizeGitPush, every ref"]
726
- burrow["Burrow<br/>Artifacts provider and repository<br/>host-held credentials"]
727
- events["App events<br/>journal → onGitPush → env.EVENTS<br/>webhooks · Workflow triggers"]
728
- client --> auth --> admission
729
- admission -- "push: ask first" --> policy
730
- admission -- "admitted bytes" --> burrow
731
- burrow -- "accepted refs" --> events
732
- ```
733
-
734
- - **Authentication** is the host's own `auth`. The owner key is a Bearer token;
735
- a named key may also be the Basic password from a git credential helper. A
736
- Workflow Git pass (a `wgp.` Bearer header, never in a URL) goes only to
737
- `host.git.workflowPass`; without that port it admits nothing. Anonymous
738
- requests never clone or push.
739
- - **Git admission** reopens the live installation before every provider call: it
740
- must be enabled and its Release must declare `git.repository`. The tenant
741
- scope prefixes every repository name (`<installation>--<repo>` for the default
742
- tenant), so an installation reaches only its own repositories. A Workflow
743
- writer may push only the branches its grant names.
744
- - **The App's push policy** answers `authorizeGitPush` for every ref update
745
- before any bytes reach the provider. One refusal rejects the whole push with
746
- Git's native `ng` report. Unsupported receive-pack commands, including signed
747
- push certificates, fail closed.
748
- - **Burrow** owns the provider and the repository. The host's Artifacts adapter
749
- mints short-lived credentials through it and forwards the admitted smart-HTTP
750
- exchange (up to 64 MiB per request); the App sees repository names, git
751
- objects and its own events, never a credential or remote.
752
- - **App events** start from the accepted-ref journal. Delivery calls the
753
- selected Instance's `onGitPush` when the Release declares
754
- `receives: ["git.push"]` and `git.repository`. The App emits typed events
755
- through `env.EVENTS`: Oyster delivers them as signed Standard Webhooks, and a
756
- host with Cloudflare Workflows (the Hub, or a standalone host's root) starts
757
- the Workflow triggers armed on that event.
758
-
759
- Agent approval stays owner-direct in both compositions: the approval routes are
760
- owner routes, refuse App-origin requests, and are never an `OysterCapability` an
761
- App can be granted.
762
-
763
- #### Git bindings, journal and lower-level ports
764
-
765
- A Release's `backend.bindings` determines whether its App gets `env.GIT`
766
- (Cloudflare Artifacts, scoped to its installation; credentials stay in the host)
767
- or `env.EVENTS` (delivered as Standard Webhooks to subscriptions the owner
768
- creates at `/api/webhooks`). Each binding enforces its declared operations.
769
- `await env.GIT.cloneUrl(repo)` returns the host-issued clone URL; an undeclared
770
- binding grants nothing. Declaration changes invalidate the loader entry even
771
- when the backend bytes stay the same. Agents push with keys from `/api/keys`.
772
-
773
- Hosts compose one `createAdmittedGit` with an installation-scoped store, live
774
- host grants, the App's typed `authorizeGitPush` policy and an accepted-ref
775
- journal. `GitWriter`, `GitPushQuestion`, `GitPushVerdict` and accepted facts
776
- come from `@fungi.computer/agar/git`; the shared wire parser is in
777
- `agar/git-wire`.
778
-
779
- An App's own `GIT` binding uses `admitted.binding(onBehalfOf)`. Its writer is
780
- `installation`, with the host-attested caller retained in `onBehalfOf`. These
781
- writes skip the App's external-push policy, retain live host admission and enter
782
- the same accepted-ref journal. The journal records only refs accepted by the
783
- provider and commits before the exchange is acknowledged. Redelivery keeps the
784
- complete original fact and `eventId`; handlers record that ID with their
785
- effects.
786
-
787
- `createGitPushJournal` composes the standalone Instance's SQLite owner with
788
- Carrier delivery and an alarm hook. Its accepted fact, ref tips and Carrier send
789
- commit together; Carrier retains delivery attempts across restarts and retries.
790
- The Hub composes its ref journal and `TeamPost.sendGitPush` in one host
791
- transaction. Neither HTTP routing nor the provider adapter creates a second push
792
- fact.
793
-
794
- `createGitDoor` from `@fungi.computer/oyster/git` accepts the host's
795
- `authenticate`, `isPublic` and `git` ports. `authenticate` receives the request
796
- and the exact installation, repository and read/write scope it names. The last
797
- returns an `AdmittedGit`; the door forwards reads to `.read` and pushes to
798
- `.push`. Provider credentials stay inside the storage adapter. `createOyster`
799
- builds these ports from `host.auth`, `host.installations` and `host.git`, so
800
- most hosts set `host.git` and never call `createGitDoor` directly. There a named
801
- key signs Git in only for installations its own grants reach: a clone needs App
802
- read and a push needs App use; otherwise the door refuses it.
803
-
804
- A host whose Workflow run owner issues Workflow Git credentials supplies
805
- `workflowGitPass` in `oysterGitRoot` or `oysterWorkerGit` options. The run owner
806
- issues one credential per native command of an admitted Git step and gives it
807
- only to that command's Git environment. It travels only as an
808
- `Authorization: Bearer` header starting with Braid's `workflowGitPassPrefix`
809
- (`wgp.`) on the ordinary credential-free door URL; it is never part of a URL.
810
- That header is admitted only by the port, for one repository and scope, as the
811
- arming member under the Workflow's branch grant, and never as a session or key.
812
- It stops working when its command closes or its run ends. Pushes outside those
813
- branches are refused before the App's push policy runs.
814
-
815
- ### Provide App capabilities
816
-
817
- Each `OysterCapability` supplies its Agar `id` and `version`, a mount `base`,
818
- relative declared `routes` (a `routes()` table from
819
- `@fungi.computer/oyster/authorization`, where every route names its requirement:
820
- `owner`, `agent`, `computer`, `member`...), and `methods`. Each method
821
- descriptor has `kind`, `method` (HTTP method), and `path` (relative route).
822
- `CapabilityMethodKind` is `json | transport | read | write`: JSON calls return
823
- decoded data, transports return Fetch handles, and reads/writes return Agar's
824
- stream handles.
825
-
826
- Method paths may contain named parameters, such as `:agentId/sessions`. Oyster
827
- uses `path-to-regexp` to compile input fields into those parameters; remaining
828
- scalar fields become query parameters for GET and handle calls. Other JSON calls
829
- keep their remaining fields in the request body. Transport handles append their
830
- Fetch pathname below that resolved route and may declare `method: "ANY"` to
831
- retain the request's HTTP method. JSON results, including Agar's
832
- `{ kind: "pending", retryAfterMs }`, reach the App unchanged; the page does not
833
- poll on the App's behalf.
834
-
835
- For example, a directory method uses
836
- `{ kind: "json", method: "GET", path: "list" }`; a file read uses
837
- `{ kind: "read", method: "GET", path: "content" }`. `fileCapabilities(source)`
838
- from `@fungi.computer/oyster/files` supplies the three file contracts over the
839
- existing `/files/` GET, PUT and POST routes.
840
-
841
- The page offers a capability only when the installed Release declares its ID and
842
- `admits` allows the principal. Every route request also rechecks that
843
- declaration and admission using the `X-Oyster-Installation` header set by the
844
- page; a read grant does not authorize the write route sharing its file mount.
845
-
846
- Consent approves capabilities, like OAuth scopes. An App upgrade may add a
847
- method that uses an already-approved capability without asking again. A new
848
- capability always needs approval. Release selection intersects stored operation
849
- and resource approvals; it never adds a grant. Every Worker call receives only
850
- the bindings allowed by that method's declared `requires`, rather than all the
851
- App's approved capabilities.
852
-
853
- The `agent.manage` consent wording is **Can create Agents; write abilities need
854
- your approval.**
855
-
856
- The `apps.call` permission also shows the declared target Apps and methods. Its
857
- route approvals retain those exact pairs: adding or renaming a target method
858
- needs owner approval. On Oyster these page calls run as the signed-in member
859
- through the target App's ordinary method gate; Agents and keys cannot use this
860
- path. The target receives its own grants, never the caller App's grants. The Hub
861
- shows the same consent list but does not offer this page capability.
862
-
863
- ### Connect an agent over MCP
864
-
865
- Connect your MCP client to `https://<your-oyster>/mcp` with
866
- `Authorization: Bearer <key>`. Installed App methods are available through
867
- `execute` as `env.<APP>`; a dotted method is a nested property, e.g.
868
- `env.BONSAI.repos.list({})`; discover them with `forage.search` and
869
- `forage.describe`. A key's or Agent's App writes run under the owner's stored
870
- approval of its App tools (recorded when the owner creates the key), so a
871
- headless client such as `claude -p` can write. That approval already covers
872
- every App on this Oyster, including ones installed after the key existed, with
873
- no per-call prompt; anyone holding the key can act as the owner in those Apps,
874
- and revoking the key is what stops it. Every other write, including the owner's
875
- own calls, requires a client that supports form elicitation and explicit
876
- approval; anonymous callers are refused.
877
-
878
- When the host has a Computer, the catalog also holds it as
879
- `env.computers.workspace`, e.g.
880
- `env.computers.workspace.exec({ command: "ls", cwd: "/workspace" })`. Its
881
- operations are the ones every Computer advertises (`read`, `list`, `write`,
882
- `mkdir`, `bash`, `exec` and the process tools), and each call asks for approval.
883
- The host supplies `computer(principal)` on its workspace: it returns the
884
- Computer's calls for a caller with Computer access and `null` otherwise. The
885
- standalone host gives an owner, key or member the same Computer grant its
886
- `/computer` routes use; Agents get none. The Computer accepts every call against
887
- that grant. `oysterComputerTools(host, principal)` from
888
- `@fungi.computer/oyster/mcp` returns this Knapsack source and its `grants`.
889
-
890
- Workers route every MCP request to the tenant's `MCP` Durable Object. Export
891
- `OysterMcp` from `oyster/workers` for the default host, or derive it from
892
- `createOysterGitMcpOwner(root)` with the same root passed to
893
- `createOysterGitWorker(root)`. Declare the `MCP` binding and SQLite migration as
894
- shown in the standalone example, and configure `OYSTER_ORIGIN`.
895
-
896
- The owner authenticates every request. SDK session IDs, event data and closure
897
- belong to that owner; deleting a session releases its catalog connection. If an
898
- owner restarts and cannot restore its live SDK transport, the old ID
899
- returns 404. Close the client's old transport and initialize a fresh session.
900
- Pending execution and elicitation are never replayed. Node hosts retain their
901
- explicit MCP adapter and call its `close()` when shutting down.
902
-
903
- Agent and key adapters use `await oysterAppMethods(host, principal, access)`
904
- from `@fungi.computer/oyster/mcp`. Pass the result in Mycelium's `sources`; its
905
- `grants` names each captured module at the level (`read`/`write`) the caller
906
- actually holds for it, so Mycelium itself refuses a write call up front when a
907
- module's own grant is `read`. For an Agent, `access` is
908
- `{kind: "agent", policy}`, the host's one stored, blanket
909
- `{level, revision, grantedBy}` approval; missing it grants no tool access. For a
910
- named key, `access` is `{kind: "key", keyId, byInstallation}`, one
911
- `{level, revision, grantedBy}` per installation the key's own Ear Tag grants
912
- admit (`appToolAccess` in `authorization.ts`); an installation the key has no
913
- grant for is absent from `byInstallation` and never listed at all, not merely
914
- refused. A key's grants are set once, at `POST /api/keys`, and never edited: to
915
- change them the owner revokes the key (`POST /api/keys/revoke`) and issues a new
916
- one. A module grant does not approve an App operation. The gate also intersects
917
- the installation's explicit approvals with its verified Release; `external`
918
- methods are refused with `approval_required`. MCP uses this same projection.
919
- Capture again when tool policy, installation authority, a key's own grants or a
920
- Release changes; the source represents one immutable catalog snapshot.
921
-
922
- ### Approve an Agent's App tools
923
-
924
- An App with `agent.manage` can create Agents and request tool-policy changes.
925
- The host records the admitted installation; those requests remain pending and
926
- have no `grantedBy`. Only direct owner approval grants App tools. The standalone
927
- owner key resolves through the seeded tenancy registry: `grantedBy` is the
928
- canonical stored member ID, while `OYSTER_OWNER_NAME` is an identity label. The
929
- stored approval pins that member's `membershipVersion`; demotion and
930
- re-promotion, removal and re-addition, or suspension and reactivation require
931
- new approval. Old policy rows also require re-approval.
932
-
933
- The authenticated owner reads `GET /api/agent-policies/:agentId` for the current
934
- `expectedRevision`, then sends `PUT` to the same path with
935
- `{"level":"write","expectedRevision":"<the returned revision>"}` (or `null` when
936
- no policy exists). These host-owned routes reject an App installation header.
937
- The Agent must have its host-minted directory/tenant pin; another tenant or an
938
- unpinned Agent refuses. A stale revision returns 409, an unknown Agent returns
939
- 404, and malformed approval input returns 400.
940
-
941
- ### Connect an Agent to a remote MCP server
942
-
943
- Connect a Streamable HTTP MCP server once, then choose which Agents can use it.
944
- Each Agent's codemode sees its granted tools as `env.mcp.<name>.<tool>()`,
945
- beside the installed Apps. Oyster keeps credentials sealed on the owner side.
946
- Agents receive access without receiving tokens, and the API never returns stored
947
- secrets.
948
-
949
- `GET /api/connections` returns the shared connections, their Agent grants, the
950
- available Agents and the OAuth `callbackUrl`. Create a connection with
951
- `POST /api/connections` and
952
- `{"name":"linear","url":"https://mcp.example.com/mcp","bearer":null}`. The name
953
- starts with a lowercase letter and contains up to 32 lowercase letters, digits
954
- or `_`. The endpoint must be `https:` with no credentials or fragment.
955
-
956
- Use `bearer:null` for an unauthenticated server, or set `bearer` to its static
957
- token. For OAuth, keep `bearer:null` and add `oauth:{}`. You can provide
958
- `clientId`, `clientSecret` and `scope` inside `oauth` when needed. Without a
959
- client ID, Oyster uses the server's dynamic client registration. The response
960
- contains `connectionId` and `authorizeUrl`. For OAuth, open `authorizeUrl` in
961
- your signed-in owner browser to finish connecting. If you register your own
962
- OAuth client, use the `callbackUrl` returned by `GET /api/connections`.
963
-
964
- A new connection grants no Agent access. Send
965
- `PUT /api/connections/:connectionId/agents/:agentId` with `{"access":"read"}`,
966
- `{"access":"all"}` or `{"access":["tool_name"]}` to grant or change access.
967
- `GET /api/connections/:connectionId/tools` lists the available tool names.
968
- `DELETE` on the Agent grant path removes only that Agent's access.
969
- `DELETE /api/connections/:connectionId` revokes the shared connection for every
970
- Agent. A repeated connection name or a grant beyond 16 connections per Agent
971
- returns 409. These routes are owner-direct and reject an App installation
972
- header.
973
-
974
- ### Give an Agent a browser
975
-
976
- Declare a Cloudflare Browser Rendering binding and every Agent gets a
977
- `cloudBrowser` tool for public pages: `open` a driven session (optionally at a
978
- URL), `navigate`, read it with `snapshot` (a bounded accessibility-tree
979
- summary), `click`, `type`, `press`, `scroll`, and `close` it.
980
-
981
- ```jsonc
982
- // wrangler.jsonc
983
- "browser": { "binding": "BROWSER" }
984
- ```
985
-
986
- Every URL the Agent supplies must be http(s), carry no credentials and resolve
987
- to a public address; anything else is refused before the browser sees it. A
988
- standalone Oyster allows two open sessions at once, closes one after 5 idle
989
- minutes or 30 minutes in all, and is billed by Cloudflare to the owner's
990
- account. Without the binding the tool is absent.
991
-
992
- Hosts compose the same module, `@fungi.computer/oyster/browser`, behind one port
993
- (`BrowserHost`): a provider (`bindingSessions(env.BROWSER)`, or
994
- `browserRunSessions` with a Browser Run account token, which also enables the
995
- `markdown`/`links`/`scrape`/`extract` Quick Reads), a required metering owner
996
- and an event sink. `createBrowser` owns lease ownership, the URL policy, reaping
997
- and billing order; `browserCapabilitySource` is the Agent tool. The Agent never
998
- reaches raw CDP or runs script in the page. See the
999
- [API reference](docs/api/browser.md).
1000
-
1001
- ### Pack an App
1002
-
1003
- `packRelease` composes `oyster/build`'s source capture, candidate preparer,
1004
- compiler and local artifact writer. Pass `sourceDirectory` as the repository
1005
- root, an explicit `sourceRevision` (`git:<full commit SHA>`), and `recipe`.
1006
- Every entry is relative to that captured repository root. Dirty files and
1007
- external build outputs are not inputs. The result retains `release.json` plus
1008
- `artifacts/`, ready for `installRelease`. This example packs the
1009
- [Notes example App](https://github.com/fungi-computer/oyster/tree/main/examples/notes-app)
1010
- kept at the root of its own git repository, `./notes-app`:
1011
-
1012
- ```ts
1013
- import { execFileSync } from "node:child_process";
1014
- import { packRelease } from "@fungi.computer/oyster/pack";
1015
-
1016
- const commit = execFileSync("git", ["-C", "./notes-app", "rev-parse", "HEAD"], {
1017
- encoding: "utf8",
1018
- }).trim();
1019
-
1020
- await packRelease({
1021
- appId: "app_notes",
1022
- sourceDirectory: "./notes-app",
1023
- sourceRevision: `git:${commit}`,
1024
- recipe: {
1025
- entry: "ui/index.html",
1026
- assets: {
1027
- maxManifestBytes: 1_048_576,
1028
- maxObjects: 1024,
1029
- maxObjectBytes: 16_777_216,
1030
- maxTotalBytes: 67_108_864,
1031
- },
1032
- assetBase: "./",
1033
- maxOutputBytes: 67_108_864,
1034
- backend: {
1035
- entry: "backend/index.ts",
1036
- exportName: "Notes",
1037
- compatibilityDate: "2026-09-04",
1038
- runtime: { kind: "durable-facet", stateSchema: 1 },
1039
- },
1040
- },
1041
- outDirectory: "./notes-release",
1042
- });
1043
- ```
1044
-
1045
- The canonical compiler reads the nearest package's `fungi.app` declaration,
1046
- including capabilities and commands for UI-only Apps. Backend Apps declare
1047
- `fungi.backendDefinition`; the emitter derives the API and declaration from that
1048
- definition and `fungi.app` in the same build that produces the Worker.
1049
- Handwritten package API methods are refused. Closed source HTML recipes
1050
- (including Notes, Bonsai and Inkcap) build captured source.
1051
- `kind: "bundled-html"` instead accepts committed, ready assets such as
1052
- `bundle/index.html`, with an explicit asset policy.
1053
-
1054
- `installFromSource` accepts `appId`, `recipe`,
1055
- `source: {remote, token, sourceRevision}` and the destination Oyster's `url`,
1056
- `key` and `installationId`. It uses the maintained Artifacts Git capture, the
1057
- same build/writer composition, then `installRelease`, and cleans its temporary
1058
- output. Source credentials and the destination owner key remain separate.
1059
- `installRelease` uploads a packed Release and makes one
1060
- `POST /api/installations` naming the installation. The host's one
1061
- install-or-select owner installs it (201) or, when the installation already
1062
- exists, switches it to that Release (200); the App keeps its state, and every
1063
- other refusal is returned unchanged.
1064
-
1065
- Pending installation commands retain their exact baseline, reduced plan and
1066
- preparation evidence for recovery. Settlement replaces those payloads with the
1067
- request's input digest, correlation, settlement time and recorded outcome. The
1068
- existing Registry alarm deletes superseded settled journal entries in bounded
1069
- batches after 90 days from their own settlement. The latest settled entry per
1070
- effective installation is always pinned, including while newer work is pending.
1071
- Indexed durable deadlines re-arm the same alarm when idle; pending recovery is
1072
- never age-deleted. Expiry removes App journal history, not canonical
1073
- installations, Releases, artifact bytes or Watchdog's private job history. An
1074
- expired operation is no longer readable; re-admitting its ID is refused as
1075
- `unavailable` when Watchdog still retains that job, rather than creating pending
1076
- work that cannot execute. A new intent needs a new request ID.
1077
-
1078
- A retained successful receipt keeps its original generation, instance and
1079
- authority-version reference. Its `installation` is resolved only from the exact
1080
- current canonical selection; after removal, generation change or selection drift
1081
- it is `null`, while the original success remains recorded. Completion helpers
1082
- return `409 installation_result_unavailable` in that case, and the standalone
1083
- installer does not approve defaults from historical success. Settled history is
1084
- never an executable recovery command. Stores containing superseded preview
1085
- journal shapes require separately authorized current-contract republishing, not
1086
- an in-place conversion.
1087
-
1088
- ## Build a shell
1089
-
1090
- The shell client lives in its own package,
1091
- [`@fungi.computer/nacre`](../nacre/README.md): workbench host, command host,
1092
- keys, commands, window manager, App directory rows and the shell-module
1093
- contract. Oyster's page uses it; a shell imports it directly.
1094
-
1095
- `@fungi.computer/oyster/page` mounts one installed App's page and connects its
1096
- sandboxed frame with that installation's admitted slots. That page is only the
1097
- framed App: menus, the command palette, status bars and every other piece of
1098
- desktop chrome belong to the shell.
1099
-
1100
- ### The shell is trusted
1101
-
1102
- A shell is not a framed App. When an owner opens the home installation, the page
1103
- is served with an empty `#oyster-shell` root and the host's page script renders
1104
- the shell there, in the top-level document. The shell runs with the host's
1105
- escalated permissions: it reads the installation directory and opens, arranges
1106
- and closes every App. Choose a shell you trust, as you would choose the host
1107
- itself.
1108
-
1109
- Child Apps stay isolated. `WorkbenchHost.mount(container, launch, events)`
1110
- mounts each App in its own sandboxed, cross-origin frame (`appSandbox`), inside
1111
- the `container` slot the shell hands it. The shell keeps one stable slot per
1112
- window and moves that window with transforms, so the frame moves, clips to the
1113
- window's rounded corners and stacks below shell menus in the same rendered
1114
- frame. Slots are never re-parented, and a minimized window keeps its frame
1115
- mounted, so restoring it never reloads the App. A click inside a frame never
1116
- reaches the shell; the App's own focus report raises its window. Every child
1117
- keeps its own configuration and capabilities; nothing granted to the shell is
1118
- lent to it. Read the home installation's own handles with
1119
- `oysterShellHandles(readOysterPageConfig())`, and connect each child frame with
1120
- `connectOysterApp`.
1121
-
1122
- The standalone root chooses its home by installation ID. Oyster core imports no
1123
- home App: it serves the selected enabled installation, or its installation list
1124
- when no home is available. `@fungi.computer/oyster/root-data` adapts the
1125
- existing installation and verified Release owners into shared workbench metadata
1126
- and opens the existing SQLite App-storage owner with fresh admission. The
1127
- deployable Bonsai root mounts Tourtois's own `PlatformControlsView`, offering
1128
- desktop and App settings. Unsupported hosted administration and platform
1129
- destinations are not offered; Computer inventory and Gill resource reads
1130
- currently refuse.
1131
-
1132
- The workbench host handle offers `memberAvatar()` as a read-only projection of
1133
- the signed-in member's catalog-validated avatar preference. Consumers refresh
1134
- that read when host settings change. Account writes remain Hub-owned.
1135
-
1136
- ## Core concepts
1137
-
1138
- ### Authorization
1139
-
1140
- `@fungi.computer/oyster/authorization` is Oyster's one authorization owner.
1141
- Every route is registered through `routes()` with a typed requirement
1142
- (`publicRoute`, `door`, `owner`, `member`, `app`, `apps`, `agent`, `agents`,
1143
- `computer`), and a table's `serve` is the only router the host builds: an
1144
- undeclared route is not served, and a handler receives only what its requirement
1145
- admitted. The owner reaches everything. A named key reaches exactly its Ear Tag
1146
- grants: `apps.read`/`apps.use` per installation (including that App's Git
1147
- repositories), `agents.use` per Agent, and `computer.use` for the Computer, its
1148
- workspace files and media. An Agent reaches its approved App tool policy;
1149
- nothing anonymous reaches an App. `owner("direct")` refuses App-mediated
1150
- requests, so consent, keys and secrets never ride an App.
1151
-
1152
- ### Owner state and selection
1153
-
1154
- The host calls `apply` with the complete owner-issued state, then `fetch` or
1155
- `call` with the admitted selection. Both identify the Instance, owner, App,
1156
- Release and authority version. Oyster persists the version the owner supplied;
1157
- it never increments another owner's authority or trusts a guest's claim to it.
1158
-
1159
- | Owner state | Runtime behavior |
1160
- | ----------- | --------------------------------------------------------------- |
1161
- | `enabled` | Resolve and activate the eligible backend. |
1162
- | `disabled` | Fence new requests and abort connections while retaining state. |
1163
- | `deleted` | Record deletion, abort, purge state and retain a tombstone. |
1164
-
1165
- An exact owner-state retry returns its recorded result. Changed input at the
1166
- same version conflicts. Older versions are stale. Disable or delete can be the
1167
- first state delivered. Re-enable requires a later owner operation. A same-schema
1168
- Release replacement keeps backend state. A changed schema fails with
1169
- `state_schema_migration_unsupported`; Oyster invents no migration policy.
1170
-
1171
- ### Ports
1172
-
1173
- `createAppInstance` is the Effect core. Its host supplies `read`, `write`,
1174
- `resolve`, `abort`, `purge` and `connect` for one stable Instance ID. `resolve`
1175
- returns the selected Release's verified durable backend: runtime profile,
1176
- state-schema version, compatibility date, export name and bundled ESM under an
1177
- immutable digest. Admission takes the lifecycle lock while acquiring a
1178
- connection; waiting on App code does not hold that lock, so disable and delete
1179
- can abort in-flight work.
1180
-
1181
- ### Scoped App storage
1182
-
1183
- `@fungi.computer/oyster/app-storage` exports `createAppStorage`, the SQLite
1184
- owner for declared App keys. Supply the database connection and an atomic
1185
- `commit` callback. `open(authorize)` binds a member view;
1186
- `openInstallation(authorize)` binds lifecycle work to the shared team layer.
1187
- Each operation rechecks live admission. Member-scoped lifecycle reads and writes
1188
- reject with `owner_required`.
1189
-
1190
- The standalone backend receives `env.APP_STORAGE` only for operations admitted
1191
- by its verified declaration and approved grants. Export `OysterBinding`, the one
1192
- guest binding entrypoint, beside `OysterInstance` and `OysterRegistry` from your
1193
- Worker entry. A root that omits it refuses every backend frame with
1194
- `binding_unavailable`. Backend calls admit only the current instance owner;
1195
- other callers receive `owner_required`. Reads, writes and resets use the same
1196
- storage owner and invalidation stream as the UI. On the Hub, the live owner
1197
- admission also allows an owner's attached Agent to edit a declared Team layer;
1198
- losing owner authority refuses the next mutation. Storage events carry the key,
1199
- scope and revision; they do not identify an Agent.
1200
-
1201
- Writes and resets check the expected revision, declared scopes, size and quotas.
1202
- After commit, `events(key)` publishes bounded invalidations; its first `null`
1203
- value marks an armed subscription. Installation and membership deletion use
1204
- `purgeAppStorageInCommit` and `purgeAppMemberStorageInCommit` inside the
1205
- caller's transaction. `appStorageSchemaStatements` retains the existing SQLite
1206
- table names.
1207
-
1208
- ### Durable Object composition
1209
-
1210
- Activation is host-gated before selection writes or aborting the old version.
1211
- The candidate backend loads in a unique isolate over one bounded disposable
1212
- sibling facet, `candidate`, with denied test bindings and no outbound network.
1213
- The lifecycle supplies its already-read prior state schema: first activation
1214
- uses empty SQLite; an initialized Instance requires the native facets API to
1215
- copy `app` into `candidate` before construction. A host without clone support
1216
- refuses that check rather than substituting fresh storage. Cleanup aborts and
1217
- deletes the sibling, and Instance purge also deletes that known name. The copy
1218
- is a construction test, not a backup or data rollback. It cannot become the live
1219
- facet and contains no supervisor selection, authority, Team App storage, or live
1220
- bindings. Native copying and isolation require the qualified runtime proof; the
1221
- fresh-SQLite Node adapter is not that proof. The host also checks the immutable
1222
- UI entry in a zero-grant browser session (`reportBootPage` with
1223
- `checkBootPage`): the page opens the pinned `/_boot/<release>/` route on the
1224
- host's own origin (https, or http only on loopback) with a short-lived
1225
- capability, and every request to any other origin is blocked. The UI result is
1226
- reported, never authority: a page that did not mount is `failed`, and a missing
1227
- browser, a timeout, unconfirmed cleanup or an unavailable runner is
1228
- `not_checked`. An App manifest, callback or healthy flag cannot supply the
1229
- verdict. This is construction and UI-mount qualification, not an HTTP request
1230
- smoke, execution against live storage, or a data rewind.
1231
-
1232
- Each check owns one provider session and confirms it closed before reporting;
1233
- unconfirmed closure reports `boot_cleanup_failed`, and Browser Run's
1234
- `keep_alive` remains the backstop.
1235
-
1236
- `pnpm run test:recovery-copy:celld` exercises the actual construction helper
1237
- with synthetic App state, a successful copy and a constructor refusal. It checks
1238
- live state preservation, denied bindings/outbound access, supervisor separation
1239
- and empty storage on reopening the cleaned sibling. It does not prove physical
1240
- file/stream deletion, restart recovery, or owner selection.
1241
-
1242
- The disposable both-host proof is
1243
- `bash apps/hub/scripts/check-app-boot-native.sh` from the repository root, after
1244
- the affected dependency and Oyster builds. It requires Linux network namespaces,
1245
- passwordless local `sudo`, the pinned celld binary and provisioned Playwright
1246
- Chromium. Inside an unnamed private network it drives a local Chromium through
1247
- the same `checkBootPage` both hosts use (a test-only provider in Browser Run's
1248
- devtools API shape) and fresh local fixture storage; it does not install a
1249
- service, contact a live host or exercise an App's HTTP handler. It checks real
1250
- construction and ordinary Agar UI mounting through each host's `/_boot/` route,
1251
- native facet cleanup, closed browser sessions, retained selections on refusal,
1252
- forged verdicts, wrapper tampering and browser unavailability.
1253
-
1254
- The Hub's real Team default-provisioning selection path is qualified separately
1255
- with `bash apps/hub/scripts/check-app-boot-native.sh --publication`, under the
1256
- same prerequisites. Its five host-dependent cases use fresh native resources,
1257
- the maintained artifact writer/readback and immutable R2 object versions. Other
1258
- domain-test metadata seeds are not host proof. This leg qualifies selection
1259
- admission, not downstream projection delivery or deployment.
1260
-
1261
- `createCloudflareAppInstance` keeps supervisor state in a SQLite Durable Object
1262
- and runs the backend in a named `app` facet loaded through the Worker Loader.
1263
- Supervisor metadata and the backend's database are separate, and a new Release
1264
- keeps the facet's database. The loader key includes the Instance ID and artifact
1265
- digest, so separate Instances of one Release never share guest module scope.
1266
- Guest code receives only the `bindings()` its host builds, no ambient outbound
1267
- access, and requests carry only `Content-Type` and the host-admitted actor,
1268
- Computer and resource headers.
1269
-
1270
- One Instance shares its guest between up to eight verified foreground reads.
1271
- Writes, raw backend requests, Gills, replay and supervisor-exclusive work run
1272
- alone; a waiting exclusive caller holds back later reads. Every completed frame
1273
- closes its own authority, and packets naming that finished frame refuse. Guest
1274
- work runs only while at least one frame on that Instance remains admitted: the
1275
- last frame stops the guest, then closes its authority, then releases admission.
1276
- Arrivals wait while that stop is in flight. Once the opening frame's deadline
1277
- passes, new reads wait for the cohort to drain rather than prolonging the guest.
1278
- Revocation, expiry and a verified write preempting replay still stop it at once.
1279
- Stopping the guest does not erase the facet's durable database.
1280
-
1281
- ## API reference
1282
-
1283
- The core is `@fungi.computer/oyster`; the Durable Object adapter is
1284
- `@fungi.computer/oyster/cloudflare`. The generated
1285
- [API reference](docs/api/README.md) is included in the tarball.
249
+ pages with them. Add Wrangler as a dev dependency to run or deploy a Worker, and
250
+ `@fungi.computer/computer` for the standalone host's Computer.
1286
251
 
1287
252
  ## Examples
1288
253
 
1289
- `examples/standalone` ships in the npm package, ready to copy as in the quick
1290
- start. The generated API reference and the in-memory example below ship with
1291
- them. The rest live in the
1292
- [Oyster repository](https://github.com/fungi-computer/oyster):
1293
-
1294
- - `examples/standalone` is the whole host from the quick start.
1295
- - `examples/notes-app` is a full App: UI, backend methods and SQLite. Copy it to
1296
- start an App with a backend. `test/standalone.native.mjs` packs it, installs
1297
- it on the standalone Oyster and drives its UI in a browser, on workerd and on
1298
- celld.
1299
- - `examples/notes.js` is a small backend with its own SQLite and no external
1300
- grants. It reads or writes one note.
1301
- - `src/testing/worker.ts` with `wrangler.test.jsonc` hosts Instances in a
1302
- Durable Object with a Worker Loader. The same pre-bundled Worker runs under
1303
- `wrangler dev` (workerd) and `celld dev`.
1304
- - `test/core.mjs` exercises replay, state transitions and owner fences in plain
1305
- Node.
1306
-
1307
- ### Drive one Instance in memory
1308
-
1309
- This self-contained example drives one Instance through in-memory ports. A
1310
- disabled Instance never resolves or connects a backend, so no Release is needed.
1311
- The request runs in a frame from `createInvocationGate`, the same gate the
1312
- standalone Instances and the Hub open for every call; the example is
1313
- `docs/home.ts`, which the package docs check typechecks.
1314
-
1315
- ```ts
1316
- import * as Effect from "effect/Effect";
1317
- import * as Schema from "effect/Schema";
1318
- import {
1319
- AppInstanceError,
1320
- createAppInstance,
1321
- instanceIds,
1322
- ownerStateSchema,
1323
- type Instance,
1324
- } from "@fungi.computer/oyster";
1325
- import {
1326
- APP_INVOCATION_CEILING_MS,
1327
- createInvocationGate,
1328
- invocationFactsSchema,
1329
- } from "@fungi.computer/oyster/invocation";
1330
-
1331
- const instanceId = instanceIds.instance.generate();
1332
- let stored: Instance | null = null;
1333
- const instance = createAppInstance({
1334
- instanceId,
1335
- read: () => Effect.succeed(stored),
1336
- write: (record) =>
1337
- Effect.sync(() => {
1338
- stored = record;
1339
- }),
1340
- resolve: () => Effect.fail(new Error("No Releases in this example")),
1341
- abort: () => Effect.void,
1342
- purge: () => Effect.void,
1343
- connect: () => Effect.fail(new Error("No backend in this example")),
1344
- });
1345
-
1346
- const selection = {
1347
- instanceId,
1348
- owner: { kind: "installation", id: "installation_example" },
1349
- appId: "app_example",
1350
- releaseId: "rel_example",
1351
- authorityVersion: 2,
1352
- } as const;
1353
- const disabled = Schema.decodeUnknownSync(ownerStateSchema)({
1354
- ...selection,
1355
- status: "disabled",
1356
- });
254
+ - `examples/standalone` ships in the package: the whole Oyster that `try` and
255
+ the deploy steps use, with `wrangler.jsonc` for Cloudflare and
256
+ `wrangler.celld.jsonc` for celld.
257
+ - [`examples/notes-app`](https://github.com/fungi-computer/oyster/tree/main/examples/notes-app)
258
+ is a full App: UI, backend methods and SQLite. Copy it to start an App with a
259
+ backend.
260
+ - The [API reference](docs/api/README.md) shows how to pack the Notes App and
261
+ how to drive one App Instance in memory.
1357
262
 
1358
- const receipt = await Effect.runPromise(instance.apply(disabled));
1359
- console.log(receipt.status); // "disabled"
263
+ ## API reference
1360
264
 
1361
- // A request runs inside an invocation frame: the caller facts the host admitted,
1362
- // a deadline, and an abort signal the gate owns.
1363
- const gate = createInvocationGate<null>({
1364
- abortGuest: () => Promise.resolve(),
1365
- close: () => Promise.resolve(),
1366
- });
1367
- const facts = Schema.decodeUnknownSync(invocationFactsSchema)({
1368
- instanceId,
1369
- selection,
1370
- artifactDigest: `sha256:${"0".repeat(64)}`,
1371
- subject: {
1372
- kind: "call",
1373
- context: {
1374
- actor: { kind: "member", memberId: "member_example" },
1375
- computerId: null,
1376
- },
1377
- },
1378
- grants: [],
1379
- ancestry: [],
1380
- deadlineAt: Date.now() + APP_INVOCATION_CEILING_MS,
1381
- });
1382
- const refused = await gate.run(facts, null, (frame) =>
1383
- Effect.runPromise(
1384
- Effect.result(instance.fetch(frame, new Request("https://app.test/"))),
1385
- ),
1386
- );
1387
- if (refused._tag === "Failure" && refused.failure instanceof AppInstanceError)
1388
- console.log(refused.failure.code); // "instance_inactive"
1389
- ```
265
+ Start with the highest layer that fits: `standalone`, then `workers` or
266
+ `workers-git`, then `host`. The [API reference](docs/api/README.md) covers those
267
+ hosts, the building blocks they are made of, operating a deployed Oyster, and
268
+ the low-level Instance, invocation and git ports. Most of the package's other
269
+ entry points are parts that the standalone host and the Fungi Hub assemble; you
270
+ do not need them to run Oyster.
1390
271
 
1391
272
  ## Limits and errors
1392
273
 
1393
- Typed `AppInstanceError` codes distinguish stale authority, mismatched identity,
1394
- inactive or deleted state and unsupported schema replacement. The host decides
1395
- their HTTP presentation and retry behavior. Rejected admission is not a
1396
- successful empty backend response.
1397
-
1398
- Deletion persists `deleting` before purge and a `deleted` tombstone afterwards.
1399
- A later access resumes an interrupted purge; this is access-driven recovery, not
1400
- an autonomous scheduler. Recreating a facet cannot bypass the tombstone.
1401
-
1402
- Oyster is not admission. It does not decide who may install, enable or call an
1403
- App; the host must obtain that authority from its owner.
1404
-
1405
- ## Build App Releases
1406
-
1407
- `@fungi.computer/oyster/build` owns the Node source capture, pinned compiler,
1408
- declaration emission and local artifact writer used by the private Publisher.
1409
- `createLocalCommitSourceCapture` captures one Git commit into a scoped snapshot;
1410
- `createAppCandidatePreparer` builds it with `createLocalBuildExecutor` and keeps
1411
- that commit in the candidate's `sourceRevision`. `commitPreparedCandidate`
1412
- persists its output through the supplied writer and Release catalog.
274
+ An App's backend gets 1,000 ms of CPU and 50 subrequests per call unless the
275
+ host sets `guestLimits`. One git request carries at most 64 MiB. Typed
276
+ `AppInstanceError` codes distinguish stale authority, mismatched identity,
277
+ inactive or deleted state and unsupported schema changes; the host decides their
278
+ HTTP presentation. Deleting an App purges its data and leaves a tombstone.
1413
279
 
1414
- Workers use `@fungi.computer/oyster/build-contract` for the same recipe schemas,
1415
- normalization, digest and provider-neutral Effect orchestration. That entry has
1416
- no filesystem, subprocess or compiler imports. Builds execute in Node within the
1417
- host's trusted build environment; they do not execute inside Oyster request
1418
- handlers.
1419
-
1420
- Recipe paths are relative to the captured Git repository root. For an App in
1421
- `apps/notes`, use `apps/notes/ui/index.html` and `apps/notes/backend/index.ts`;
1422
- capture does not rebase paths to the App directory. The nearest `package.json`
1423
- above the entry supplies `fungi.app`, plus `fungi.backendDefinition` for an API
1424
- derived from the compiled backend.
1425
-
1426
- An App owns its recipe in `package.json#fungi.build`, alongside its existing
1427
- page policy (`react`, `stylesheets`, and dependency build declarations). Recipe
1428
- paths in that metadata are relative to the App's own directory. The Node-only
1429
- `readBuildManifest(packageJson)` decodes that one strict contract;
1430
- `appBuildRecipe(manifest, directory)` roots the recipe for a captured checkout,
1431
- or accepts `""` for an App at the repository root. Dependency-only metadata is
1432
- still valid but cannot supply an App recipe. Unknown build fields are refused.
1433
-
1434
- The starter installer reads metadata with `git show` from the selected commit,
1435
- not from dirty checkout files. Its roster owns only App identity and source
1436
- locations. The scaffold's `npm run build` deliberately reads saved working
1437
- metadata before capturing those same saved files. Its template declares the
1438
- ordinary npm recipe as `kind: "source-html"`, including the backend entry and
1439
- asset bounds; the command does not carry another copy of that recipe.
1440
-
1441
- **Breaking recipe contract:** `@fungi.computer/oyster/standalone/app-set` no
1442
- longer exposes `StarterApp.recipe` or recipe values on `standaloneAppSet`.
1443
- Callers read the selected source's `package.json` with `readBuildManifest` and
1444
- materialize it with `appBuildRecipe`, both exported from
1445
- `@fungi.computer/oyster/build`. The workspace metadata policy advances from
1446
- `package-json-fungi-build-v3` to `package-json-fungi-build-v4`; builders refuse
1447
- missing or superseded policy metadata rather than guessing a recipe.
1448
-
1449
- **Breaking repository-registration contract:** the public
1450
- `PUT /api/apps/:appId/build-source` route, which accepted an App identity in the
1451
- path and caller-supplied installation, repository, and recipe fields, has been
1452
- removed. Use repo-only `APPS.register({ repo })`, exposed by Bonsai as
1453
- `apps.register({ repo })`. The host reads App identity and `fungi.build` recipe
1454
- from the immutable main commit's root `package.json` through the shared manifest
1455
- reader; callers cannot override identity or recipe. An existing repository
1456
- registration retains its App identity on replay. Registration returns the App ID
1457
- and exact commit without starting a build or installing a Release. No
1458
- compatibility route or shim remains.
1459
-
1460
- ### Local Release installation
1461
-
1462
- ```sh
1463
- export OYSTER_URL=https://your-oyster.example
1464
- export OYSTER_OWNER_KEY='<your owner key>'
1465
- oyster install ./dist --installation-id my-app
1466
- # Or name the same Release's manifest:
1467
- oyster install ./dist/release.json --installation-id my-app
1468
- ```
1469
-
1470
- The CLI delegates to `installRelease` from `@fungi.computer/oyster/pack`, using
1471
- the same uploader as programmatic clients. Artifacts must upload before
1472
- `POST /api/installations`. Upload refusal, missing files, and non-OK
1473
- installation responses exit nonzero. No key is discovered from your home
1474
- directory, and this command does not provision a Computer or deploy an Oyster.
1475
-
1476
- For repository authoring, use Bonsai's repository Settings **Make this an App**
1477
- (or `apps.register({ repo })`). Commit the root `package.json#fungi.build`
1478
- recipe first; dirty metadata is not registration input. The readonly App ID and
1479
- editable revision/name come from registration or the latest recorded build.
1480
- Status can be read using `APPS.buildStatus({ repo })` in the captured Git
1481
- installation; Settings uses that selector after reload. No job returns `null`.
1482
- Workflow callers use `APPS.buildStatus({ jobId })` for the particular job they
1483
- started.
1484
-
1485
- ### Accepted main builds and approval-bounded installation
1486
-
1487
- The standalone Instance's accepted-ref journal delivers the host-attested main
1488
- push to Bonsai. For a registered repository, Bonsai requests the retained
1489
- Trellis build-on-merge template through WORKFLOWS. Its published run owns the
1490
- build, exact-source verification and installation steps and their result cards.
1491
- An App's change/merge payload is not push authority. The host's Workflow-node
1492
- idempotency key reuses a build job on retry or restart. A local-only Computer
1493
- returns typed no_backend before creating a new job or starting a machine.
1494
-
1495
- Only an admitted Workflow-node APPS call can install its matching successful
1496
- build's recorded Release at the recorded target. Ordinary App-origin
1497
- installation remains refused. Existing grants may be reused, but new permissions
1498
- return needs_consent without changing the running Release. A fresh installation
1499
- also returns needs_consent, even when it requests no permissions: the owner must
1500
- select the built Release directly to confirm the install. Registering a
1501
- repository as an App (**Make this an App**) does not confirm its installation.
1502
- Later Workflows can update the owner-confirmed installation within its existing
1503
- grants, never widen them. The build row records the outcome; status reads are
1504
- read-only and no native alarm resumes installation. Workflow execution owns
1505
- retries. This template has no review step, review configuration or separate
1506
- consent ledger.
1507
-
1508
- **Breaking installation contract:** Bonsai apps.install and APPS.select require
1509
- the successful build's jobId alongside installationId and release. The host
1510
- compares all recorded Release metadata and the target before installation.
1511
-
1512
- **Breaking build-port contract:** consumers of
1513
- `@fungi.computer/oyster/app-builds` must provide
1514
- `OysterBuildComputer.buildBackend()`, returning `{ kind: "hosted" }` or
1515
- `{ kind: "no_backend" }`, alongside `runBuild`. The preflight reads routing
1516
- without starting a machine. The build owner's `install(jobId, decide)` invokes
1517
- the host decision only for a successful job with a verified Release and pending
1518
- installation target; it records that decision on the same job. Terminal
1519
- installation decisions are not invoked again on replay.
1520
-
1521
- For a source HTML build, that nearest package must itself be a pnpm workspace
1522
- member, or the root package of a standalone App repository. A nested package
1523
- outside the workspace inventory fails with `WorkspaceBuildError` code
1524
- `non_workspace_package`; it never inherits the host package's dependency
1525
- closure. Notes is an explicit workspace member with its own Agar and Zod
1526
- dependencies and the builder's pinned Vite toolchain, separate from Oyster's
1527
- host runtime.
1528
-
1529
- The other tracked nested manifests are separate source inputs, not App HTML
1530
- builds inside their parent workspace:
1531
-
1532
- - `apps/bonsai/demo/koi-pond`: copied into its own demo Git repository.
1533
- - `packages/create-fungi-app/template`: copied to the generated App's root.
1534
- - `services/app-publisher/test/fixtures/size-hello`: a backend-only emission
1535
- fixture, not a workspace HTML build.
1536
- - `apps/tui/test/fixtures/fairy-ring-extension` and
1537
- `runtimes/local/test/fixtures/{extension-compactor,extension-counter}`:
1538
- installed extension fixtures, not App source builds.
1539
- - `packages/computer/container` and
1540
- `packages/cordyceps/upstream/{computerd,dofs,rpc}`: container/vendored package
1541
- inputs, not App source entries.
1542
- - `templates/vishnu-starter`: a standalone project template outside the pnpm
1543
- workspace.
1544
-
1545
- A captured UI bundle uses `kind: "bundled-html"`, an `entry` ending in
1546
- `/index.html`, `assetBase: "./"`, and an explicit `assets` policy with
1547
- `maxManifestBytes`, `maxObjects`, `maxObjectBytes`, and `maxTotalBytes`. Set
1548
- `backend: null` for UI only, or supply a repository-relative `backend.entry`
1549
- with the backend runtime, export name, and compatibility date. The compiler
1550
- joins both outputs from that same snapshot. A backend-only recipe uses its
1551
- Worker entry as `entry` and omits `backend.entry`. First-party HTML recipes
1552
- retain their catalog-owned compilation steps.
1553
-
1554
- For UI source, omit `kind` and use a closed HTML recipe entry, such as
1555
- `ui/index.html` for Notes at its repository root. It requires `assets` and
1556
- `assetBase`, and accepts `backend.entry` in the same recipe. The compiler
1557
- installs the captured lockfile, emits the catalog's ordered workspace TypeScript
1558
- projects, compiles declared stylesheets, and builds the source HTML with Vite.
1559
- Notes uses plain TypeScript; Bonsai uses React and Tailwind. Neither reads
1560
- prebuilt workspace `dist` directories or an external UI output directory.
1561
-
1562
- A workspace dependency that cannot build from its `tsconfig.build.json` names
1563
- the one `package.json` script that builds it, in place of TypeScript configs:
1564
- `"fungi": { "build": { "script": "build" } }`. The compiler runs exactly that
1565
- script, at the dependency's place in the build order, with
1566
- `pnpm run -- <script>` in the package directory and no `pre`/`post` hooks or
1567
- implicit install. Only the Computer build (`buildTeamCandidate`, composed with
1568
- `createLocalBuildExecutor({ packageScripts: "run" })`) runs it; the script is
1569
- arbitrary package code, isolated by that admitted Computer. Every other
1570
- composition, including `packRelease` and `create-fungi-app`, refuses such a
1571
- source before installing. Unknown `fungi.build` fields are refused. The policy
1572
- is pinned as `package-json-fungi-build-v4` in the recipe toolchain; an executor
1573
- refuses a recipe pinned under another policy.
1574
-
1575
- The App's HTML module scripts, shell module and selected backend select its
1576
- workspace compile roots. The maintained HTML parser and esbuild follow local
1577
- runtime imports; erased type imports and authoring scripts do not pull a host
1578
- package into that compilation. Declared package stylesheets are also roots. The
1579
- planning pass follows code imports only; the actual Vite build retains ownership
1580
- of asset loading, validation and emission. Each selected workspace package still
1581
- builds its full declared products and runtime workspace dependency closure, in
1582
- dependency order. Dependency manifests, hydration and the Computer-only
1583
- package-script guard are unchanged.
1584
-
1585
- `createLocalArtifactWriter(directory, recipe.assets)` writes the App root and
1586
- all referenced UI/backend objects. It uses the supplied asset bounds and
1587
- maintained MIME metadata. Bundled UI plus a backend may hydrate a captured
1588
- `pnpm-lock.yaml` with the pinned `pnpm@11.24.0`, frozen lockfile and no
1589
- lifecycle scripts or pnpmfile. Installs never run lifecycle scripts; the only
1590
- package script a build runs is a declared `fungi.build.script`, on a Computer.
280
+ ## Part of Fungi
1591
281
 
1592
- For Artifacts, `createArtifactsSourceCapture({ remote, token, sourceRevision })`
1593
- accepts the host's Git URL and a `git:<commit>` revision. Native Git receives
1594
- the credential through its environment, refuses redirects, and captures that
1595
- exact commit even if the branch advances. A `git.push` Workflow can prepare the
1596
- candidate in Node, commit it through the artifact writer and Release catalog,
1597
- then upload/install the Release through `oyster/pack`.
282
+ [Fungi](https://fungi.computer/) runs AI Agents on their own Computers, inside
283
+ Teams that share Agents, Computers, Apps and a bill. Oyster is its App host,
284
+ released on its own. It is built from other Fungi packages, each MIT-licensed,
285
+ in its own repository at `github.com/fungi-computer/<name>` and usable without
286
+ the rest, among them [Agar](https://github.com/fungi-computer/agar) (the App
287
+ contract), [Puffball](https://github.com/fungi-computer/puffball) (Releases),
288
+ [Shiitake](https://github.com/fungi-computer/shiitake) (Agent conversations),
289
+ [Mycelium](https://github.com/fungi-computer/mycelium) (the MCP `execute` tool),
290
+ [Burrow](https://github.com/fungi-computer/burrow) (git on Artifacts),
291
+ [Ear Tag](https://github.com/fungi-computer/ear-tag) (keys) and
292
+ [Caps](https://github.com/fungi-computer/caps) (the interface). The
293
+ [package directory](https://docs.fungi.computer/reference/packages/) lists them
294
+ all.
1598
295
 
1599
296
  ## Contribute and license
1600
297
 
1601
- Oyster is developed inside Fungi's own workspace with the rest of the family and
1602
- released to this repository with its history. There,
1603
- `pnpm --filter @fungi.computer/oyster test` runs the lifecycle checks,
1604
- `pnpm --filter @fungi.computer/oyster build` compiles the package, and
1605
- `test:standalone` and `test:standalone:celld` run a real Oyster under workerd
1606
- and under celld, install the Notes example App, call its methods and drive its
1607
- UI in a browser. The package uses the MIT license in [`LICENSE`](LICENSE).
1608
-
1609
- ## Hosting many tenants
1610
-
1611
- Pass your own `OysterTenancy` from `@fungi.computer/oyster/tenant` as the
1612
- `tenancy` of `oysterGitRoot({ tenancy })`. Its `resolve(request)` selects one
1613
- tenant from the request origin before sign-in and returns that tenant's
1614
- `TenantScope` (built with `tenantScope(tenantId, origin)`) and authentication,
1615
- or `null` to refuse an unknown origin. Oyster uses the scope for registry,
1616
- workspace, keys, webhooks and repository names, and pins each Instance to its
1617
- selected tenant. Canonical member roles remain distinct from owner authority.
1618
- Anonymous requests reach only sign-in, `robots.txt` and the digest-pinned shell
1619
- and App UI bytes; unknown origins and policy refusals fail closed.
1620
- `ownerOrKeyTenancy` is the single-tenant case.
1621
-
1622
- ## Machine link protocol
1623
-
1624
- `@fungi.computer/seam/machine-link-protocol` exposes the bounded read/leave
1625
- decoder and `createMachineLinkPostChannel`. The channel transports ordinary
1626
- Carrier Post envelopes and their receiver receipts without rewriting cargo. The
1627
- host supplies frame-byte, in-flight and acknowledgment-time limits.
1628
-
1629
- `machineLinkDialUrl(issuer, teamId, deviceId)` and
1630
- `machineLinkAudience(teamId, deviceId)` give both hosts the same GET path and
1631
- Seam audience. Enrollment is separately authorized by the account owner; a
1632
- native dial proves possession of the enrolled device key, not command
1633
- acceptance.
1634
-
1635
- The host still owns authenticated native sockets, currentness and connection
1636
- lifetime. Call `close()` when a connection is lost; create a new channel for its
1637
- successor. A closed channel, timeout or capacity failure rejects pending I/O
1638
- without asserting command refusal or custody. Carrier remains the durable outbox
1639
- and retry owner. In-flight state is not a persistent mailbox or a Capnweb
1640
- capability table.
1641
-
1642
- A Post acknowledgment is not Shiitake command acceptance. The Hub's home-aware
1643
- Agent mail route still requires the recipient's actual Accepted receipt. Focused
1644
- channel and route tests do not qualify native transport, reconnect, Hub restart
1645
- or Agent execution. The rebuild now wires Local service, Team native receiver
1646
- and hosted actual-home consumers together; their whole-bundle native
1647
- qualification and production activation remain separate claims.
1648
-
1649
- ## Approve an installed App's permissions
1650
-
1651
- After selecting a new Release, the owner can open **App access** beside the App
1652
- on the standalone owner home, or visit
1653
- `/api/installations/<installationId>/grants` directly. Review the requested
1654
- capabilities and choose **Save permissions**. Existing resource restrictions are
1655
- preserved; a newly selected capability is approved within this Oyster's scope.
1656
- This updates the installation without reinstalling the App or changing its data.
1657
-
1658
- The page sends an owner-only `PUT` to the same path, carrying the captured
1659
- `storeGeneration`, `authorityVersion`, Release `artifactDigest`, and a bounded
1660
- `{kind:"change-grants",changes:[{capability,grant}]}` command. Each grant
1661
- contains `operations` and `resources`; `null` revokes that capability. Unnamed
1662
- approvals retain their existing operation and resource ceilings. Agents, keys
1663
- and App-origin requests cannot approve. A replaced store, stale Release/version
1664
- or concurrent approval returns `409`; the page refreshes the facts and rebases
1665
- touched edits for review. The required `InstallationStore` exposes its durable
1666
- `generation()` and `compareAndPut(record, expectedVersion, expectedGeneration)`.
1667
- The latter returns a serializable commit/refusal result across Durable Object
1668
- RPC and checks both pins in the existing commit transaction.
1669
-
1670
- ## Breaking App send contract
1671
-
1672
- App `AGENTS.send` requires a caller-owned `requestId`, minted once per user
1673
- intent and reused unchanged on retry after an UNKNOWN outcome. The standalone
1674
- adapter no longer generates a replacement. See the
1675
- [App Agent send API reference](docs/overview.md#app-agent-send-api--breaking-change)
1676
- for the complete input and migration note.
298
+ Oyster is developed inside Fungi's workspace and released to its own repository
299
+ with its history. There, `pnpm --filter @fungi.computer/oyster test` runs the
300
+ lifecycle checks, and `test:standalone` and `test:standalone:celld` run a real
301
+ Oyster under workerd and celld, install the Notes App and drive its UI in a
302
+ browser. Oyster is MIT-licensed; see [`LICENSE`](LICENSE).