@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.
- package/README.md +178 -1552
- package/dist/agents.d.ts +8 -0
- package/dist/agents.js +6 -0
- package/dist/app-builds.d.ts +5 -6
- package/dist/app-builds.js +3 -10
- package/dist/apps/permissions.js +8 -1
- package/dist/auth.d.ts +2 -0
- package/dist/auth.js +9 -8
- package/dist/boot-host-script.js +1 -1
- package/dist/build/candidate-cli.mjs +4 -0
- package/dist/catalog-frame.d.ts +0 -1
- package/dist/computer.d.ts +5 -0
- package/dist/computer.js +1 -0
- package/dist/embed-metafiles.js +2 -2
- package/dist/embed-scripts.js +3 -3
- package/dist/hello-app-script.js +1 -1
- package/dist/host-page-assets.js +1 -1
- package/dist/host-page.d.ts +5 -1
- package/dist/host-page.js +23 -23
- package/dist/host.js +6 -1
- package/dist/page/app-access.js +23 -1
- package/dist/page/app-permissions.js +165 -50
- package/dist/page/app-rights.d.ts +8 -0
- package/dist/page/app-rights.js +13 -0
- package/dist/page/computer-handles.d.ts +15 -0
- package/dist/page/computer-handles.js +4 -1
- package/dist/page/mount.d.ts +5 -0
- package/dist/page/mount.js +4 -0
- package/dist/page-script.js +3 -3
- package/dist/standalone/agents.js +10 -0
- package/dist/standalone/app-set.d.ts +9 -0
- package/dist/standalone/app-set.js +43 -0
- package/dist/standalone/app-source.js +16 -1
- package/dist/standalone/builds.d.ts +2 -2
- package/dist/standalone/builds.js +4 -0
- package/dist/standalone/cloudflare-account.d.ts +10 -0
- package/dist/standalone/cloudflare-account.js +17 -0
- package/dist/standalone/computer.d.ts +8 -3
- package/dist/standalone/computer.js +26 -3
- package/dist/standalone/install-apps-cli.js +1 -1
- package/dist/standalone/local-desktop.d.ts +19 -2
- package/dist/standalone/local-desktop.js +38 -15
- package/dist/standalone/media.d.ts +2 -0
- package/dist/standalone/media.js +17 -1
- package/dist/standalone/registry.d.ts +4 -1
- package/dist/standalone/registry.js +6 -0
- package/dist/standalone/sign-in-link.d.ts +1 -1
- package/dist/standalone/sign-in-link.js +9 -18
- package/dist/standalone/try-cli.d.ts +7 -0
- package/dist/standalone/try-cli.js +88 -8
- package/dist/starter-agent.d.ts +59 -0
- package/dist/starter-agent.js +85 -0
- package/docs/api/README.md +744 -88
- package/docs/api/agents.md +6 -0
- package/docs/api/auth.md +10 -0
- package/docs/api/computer.md +4 -0
- package/docs/api/page/mount.md +2 -0
- package/docs/api/workers-git.md +14 -9
- package/docs/api/workers.md +8 -3
- package/docs/site/agent-quickstart.mdx +1 -1
- package/package.json +34 -50
package/README.md
CHANGED
|
@@ -1,22 +1,23 @@
|
|
|
1
1
|
# Oyster (`@fungi.computer/oyster`)
|
|
2
2
|
|
|
3
|
-
Oyster
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
-
|
|
19
|
-
|
|
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`,
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
`
|
|
44
|
-
`
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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.
|
|
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
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
|
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`
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
348
|
-
`
|
|
349
|
-
|
|
350
|
-
|
|
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
|
-
|
|
368
|
-
|
|
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
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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
|
-
|
|
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
|
|
380
|
-
|
|
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
|
|
154
|
+
--header "Authorization: Bearer <the oyk_ key from the answer>"
|
|
399
155
|
```
|
|
400
156
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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
|
-
|
|
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
|
-
|
|
490
|
-
Node 24, pnpm and Git; a Cloudflare account matters only for the deploy step.
|
|
172
|
+
## Build your own host
|
|
491
173
|
|
|
492
|
-
|
|
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
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
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
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
`
|
|
504
|
-
|
|
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
|
-
|
|
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
|
-
|
|
515
|
-
|
|
516
|
-
|
|
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
|
-
|
|
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
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
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
|
-
|
|
531
|
-
|
|
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
|
-
##
|
|
218
|
+
## How it works
|
|
537
219
|
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
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
|

|
|
546
232
|
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
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
|
|
241
|
+
## Install
|
|
562
242
|
|
|
563
243
|
```sh
|
|
564
|
-
|
|
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
|
|
570
|
-
|
|
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
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
[
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
-
|
|
1296
|
-
|
|
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
|
-
|
|
1359
|
-
console.log(receipt.status); // "disabled"
|
|
263
|
+
## API reference
|
|
1360
264
|
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
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
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
1596
|
-
|
|
1597
|
-
|
|
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
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
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).
|