@fungi.computer/oyster 0.13.0 → 0.14.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 +30 -15
- package/dist/agents.js +2 -1
- package/dist/approval-home.js +4 -2
- package/dist/boot-host-script.js +1 -1
- package/dist/browser/cdp-client.d.ts +1 -1
- package/dist/browser/cdp-client.js +73 -37
- package/dist/browser/errors.d.ts +2 -0
- package/dist/browser/lease-registry.d.ts +5 -1
- package/dist/browser/lease-registry.js +2 -6
- package/dist/build/candidate-cli.mjs +267 -246
- package/dist/build/definition-emission.js +17 -3
- package/dist/build/local-build.d.ts +6 -0
- package/dist/build/local-build.js +104 -91
- package/dist/build/process-group.d.ts +6 -0
- package/dist/build/process-group.js +92 -0
- package/dist/build.d.ts +1 -1
- package/dist/build.js +1 -1
- package/dist/embed-metafiles.js +2 -2
- package/dist/embed-scripts.js +1 -1
- package/dist/git-journal.js +12 -9
- package/dist/hello-app-script.js +1 -1
- package/dist/host-page-assets.js +1 -1
- package/dist/host-page.d.ts +6 -1
- package/dist/host-page.js +40 -0
- package/dist/host.js +24 -9
- package/dist/installation-operations.js +1 -1
- package/dist/machine-link/host.js +18 -13
- package/dist/pack.d.ts +3 -1
- package/dist/pack.js +28 -7
- package/dist/page/app-permissions.js +3 -13
- package/dist/page-script.js +2 -2
- package/dist/standalone/agent-mail.d.ts +38 -11
- package/dist/standalone/agent-mail.js +8 -22
- package/dist/standalone/agents.d.ts +1 -0
- package/dist/standalone/agents.js +30 -5
- package/dist/standalone/hello-app.d.ts +4 -1
- package/dist/standalone/hello-app.js +67 -22
- package/dist/standalone/hello-lesson.d.ts +2 -0
- package/dist/standalone/hello-lesson.js +36 -0
- package/dist/standalone/local-desktop.d.ts +6 -4
- package/dist/standalone/local-desktop.js +39 -20
- package/dist/standalone/sign-in-link.d.ts +2 -1
- package/dist/standalone/sign-in-link.js +58 -17
- package/dist/standalone/try-cli.d.ts +12 -9
- package/dist/standalone/try-cli.js +490 -138
- package/docs/api/browser.md +24 -7
- package/docs/api/pack.md +3 -2
- package/docs/api/workers-git.md +2 -2
- package/docs/api/workers.md +2 -2
- package/docs/site/agent-quickstart.mdx +109 -354
- package/examples/standalone/wrangler.jsonc +1 -1
- package/package.json +24 -24
package/docs/api/browser.md
CHANGED
|
@@ -96,7 +96,7 @@ The configured provider answered with a failure or is unreachable.
|
|
|
96
96
|
#### Extends
|
|
97
97
|
|
|
98
98
|
- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `op`: `string`;
|
|
99
|
-
`status`: `number` \| `null`; `message`: `string`; \}\>
|
|
99
|
+
`status`: `number` \| `null`; `message`: `string`; `cause?`: `unknown`; \}\>
|
|
100
100
|
|
|
101
101
|
#### Constructors
|
|
102
102
|
|
|
@@ -108,12 +108,13 @@ new CloudBrowserUpstreamError(args): CloudBrowserUpstreamError;
|
|
|
108
108
|
|
|
109
109
|
###### Parameters
|
|
110
110
|
|
|
111
|
-
| Parameter | Type
|
|
112
|
-
| -------------- |
|
|
113
|
-
| `args` | \{ `op`: `string`; `status`: `number` \| `null`; `message`: `string`; \} |
|
|
114
|
-
| `args.op` | `string`
|
|
115
|
-
| `args.status` | `number` \| `null`
|
|
116
|
-
| `args.message` | `string`
|
|
111
|
+
| Parameter | Type | Description |
|
|
112
|
+
| -------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
|
113
|
+
| `args` | \{ `op`: `string`; `status`: `number` \| `null`; `message`: `string`; `cause?`: `unknown`; \} | - |
|
|
114
|
+
| `args.op` | `string` | - |
|
|
115
|
+
| `args.status` | `number` \| `null` | - |
|
|
116
|
+
| `args.message` | `string` | - |
|
|
117
|
+
| `args.cause?` | `unknown` | Original transport failure retained for host diagnostics. |
|
|
117
118
|
|
|
118
119
|
###### Returns
|
|
119
120
|
|
|
@@ -128,6 +129,8 @@ Data.TaggedError(
|
|
|
128
129
|
readonly op: string;
|
|
129
130
|
readonly status: number | null;
|
|
130
131
|
readonly message: string;
|
|
132
|
+
/ Original transport failure retained for host diagnostics. /
|
|
133
|
+
readonly cause?: unknown;
|
|
131
134
|
}>.constructor
|
|
132
135
|
```
|
|
133
136
|
|
|
@@ -157,6 +160,20 @@ readonly status: number | null;
|
|
|
157
160
|
Data.TaggedError("CloudBrowserUpstreamError").status;
|
|
158
161
|
```
|
|
159
162
|
|
|
163
|
+
##### cause?
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
optional cause?: unknown;
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Original transport failure retained for host diagnostics.
|
|
170
|
+
|
|
171
|
+
###### Inherited from
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
Data.TaggedError("CloudBrowserUpstreamError").cause;
|
|
175
|
+
```
|
|
176
|
+
|
|
160
177
|
##### message
|
|
161
178
|
|
|
162
179
|
```ts
|
package/docs/api/pack.md
CHANGED
|
@@ -89,6 +89,7 @@ type PackOptions = Readonly<{
|
|
|
89
89
|
recipe: AppPublisherCoreConfigInput["recipe"];
|
|
90
90
|
packageStoreDirectory?: string;
|
|
91
91
|
outDirectory: string;
|
|
92
|
+
signal?: AbortSignal;
|
|
92
93
|
}>;
|
|
93
94
|
```
|
|
94
95
|
|
|
@@ -301,8 +302,8 @@ function installFromSource(input): Promise<Response>;
|
|
|
301
302
|
Capture an Artifacts Git commit, build its Release, upload it to an Oyster, and
|
|
302
303
|
install it, or switch an existing installation to it
|
|
303
304
|
([installRelease](#installrelease)). `waitMs` starts with the upload/observation
|
|
304
|
-
phase after packing; a supplied caller signal
|
|
305
|
-
|
|
305
|
+
phase after packing; a supplied caller signal also interrupts packing and
|
|
306
|
+
retains its original lifetime.
|
|
306
307
|
|
|
307
308
|
#### Parameters
|
|
308
309
|
|
package/docs/api/workers-git.md
CHANGED
|
@@ -1019,7 +1019,7 @@ gill(
|
|
|
1019
1019
|
title: string;
|
|
1020
1020
|
state: "error";
|
|
1021
1021
|
rows: readonly [];
|
|
1022
|
-
reason?: "exec_isolation_required" | "params_required";
|
|
1022
|
+
reason?: "disabled" | "exec_isolation_required" | "params_required";
|
|
1023
1023
|
error: string;
|
|
1024
1024
|
recovery?: | {
|
|
1025
1025
|
kind: "configure";
|
|
@@ -1078,7 +1078,7 @@ Invoke a Release-declared Gill in a fresh immutable frame.
|
|
|
1078
1078
|
`Promise`\<[`InstanceResult`](host.md#instanceresult)\< \| \{ `viewId`:
|
|
1079
1079
|
`string`; `title`: `string`; `state`: `"empty"`; `rows`: readonly \[\]; `next?`:
|
|
1080
1080
|
`string`; \} \| \{ `viewId`: `string`; `title`: `string`; `state`: `"error"`;
|
|
1081
|
-
`rows`: readonly \[\]; `reason?`: `"exec_isolation_required"` \|
|
|
1081
|
+
`rows`: readonly \[\]; `reason?`: `"disabled"` \| `"exec_isolation_required"` \|
|
|
1082
1082
|
`"params_required"`; `error`: `string`; `recovery?`: \| \{ `kind`:
|
|
1083
1083
|
`"configure"`; `param`: `string`; \} \| \{ `kind`: `"open"`; \}; \} \| \{
|
|
1084
1084
|
`viewId`: `string`; `title`: `string`; `state`: `"full"`; `rows`: readonly
|
package/docs/api/workers.md
CHANGED
|
@@ -2050,7 +2050,7 @@ gill(
|
|
|
2050
2050
|
title: string;
|
|
2051
2051
|
state: "error";
|
|
2052
2052
|
rows: readonly [];
|
|
2053
|
-
reason?: "exec_isolation_required" | "params_required";
|
|
2053
|
+
reason?: "disabled" | "exec_isolation_required" | "params_required";
|
|
2054
2054
|
error: string;
|
|
2055
2055
|
recovery?: | {
|
|
2056
2056
|
kind: "configure";
|
|
@@ -2109,7 +2109,7 @@ Invoke a Release-declared Gill in a fresh immutable frame.
|
|
|
2109
2109
|
`Promise`\<[`InstanceResult`](host.md#instanceresult)\< \| \{ `viewId`:
|
|
2110
2110
|
`string`; `title`: `string`; `state`: `"empty"`; `rows`: readonly \[\]; `next?`:
|
|
2111
2111
|
`string`; \} \| \{ `viewId`: `string`; `title`: `string`; `state`: `"error"`;
|
|
2112
|
-
`rows`: readonly \[\]; `reason?`: `"exec_isolation_required"` \|
|
|
2112
|
+
`rows`: readonly \[\]; `reason?`: `"disabled"` \| `"exec_isolation_required"` \|
|
|
2113
2113
|
`"params_required"`; `error`: `string`; `recovery?`: \| \{ `kind`:
|
|
2114
2114
|
`"configure"`; `param`: `string`; \} \| \{ `kind`: `"open"`; \}; \} \| \{
|
|
2115
2115
|
`viewId`: `string`; `title`: `string`; `state`: `"full"`; `rows`: readonly
|
|
@@ -1,397 +1,152 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Agent quick start
|
|
3
3
|
description:
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
Run Oyster locally with one command, open Hello, then edit and restart.
|
|
5
|
+
Connect MCP, build another App or deploy when you are ready.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
You are an agent setting up Oyster for a person.
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
## Before you start
|
|
18
|
-
|
|
19
|
-
- **Cloudflare plan:** SQLite-backed Durable Objects are available on Workers
|
|
20
|
-
Free; they do not by themselves require Paid. Cloudflare's SQLite-backed
|
|
21
|
-
Durable Objects limits list 30 seconds of CPU per request by default,
|
|
22
|
-
configurable to 5 minutes. See Cloudflare's
|
|
23
|
-
[Durable Objects limits](https://developers.cloudflare.com/durable-objects/platform/limits/)
|
|
24
|
-
and
|
|
25
|
-
[Durable Objects pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/).
|
|
26
|
-
- **Agent chat and AI Gateway:** By default, Agent chat uses the Workers AI
|
|
27
|
-
binding; it needs no separate provider key or Gateway setup. Prints uses your
|
|
28
|
-
account's default AI Gateway (created automatically); set `AI_GATEWAY_ID` to
|
|
29
|
-
use another. The routed models include `openai/gpt-image-2` and video IDs
|
|
30
|
-
`bytedance/seedance-2.0`, `bytedance/seedance-2.0-fast`,
|
|
31
|
-
`bytedance/seedance-2.0-mini`, `google/veo-3.1`, `google/veo-3.1-fast` and
|
|
32
|
-
`minimax/h3-max`.
|
|
33
|
-
|
|
34
|
-
- **Deployment plan:** Step 7 needs Workers Paid because this deployment uses
|
|
35
|
-
Containers for the Computer image; Cloudflare lists Containers as available on
|
|
36
|
-
the
|
|
37
|
-
[Workers Paid plan](https://developers.cloudflare.com/containers/platform/).
|
|
38
|
-
SQLite-backed Durable Objects alone do not require Paid.
|
|
39
|
-
|
|
40
|
-
## What Oyster is
|
|
41
|
-
|
|
42
|
-
- Oyster hosts Apps on one Cloudflare Worker, or on celld, a Workers-compatible
|
|
43
|
-
runtime you host yourself.
|
|
44
|
-
- Each App is an immutable Release built from an exact git commit. Its backend
|
|
45
|
-
runs in its own Durable Object with its own SQLite, and it gets only the
|
|
46
|
-
bindings it declares.
|
|
47
|
-
- People use Apps in a browser. Agents call the same App methods over HTTP or
|
|
48
|
-
through one MCP endpoint, `/mcp`.
|
|
49
|
-
|
|
50
|
-
## 1. Check prerequisites
|
|
51
|
-
|
|
52
|
-
You need Node 24 or newer, pnpm 11 or newer, Git, curl and openssl. You do not
|
|
53
|
-
need a Cloudflare account until step 7. Docker is needed only in step 7, where
|
|
54
|
-
Wrangler builds the Computer's container image.
|
|
8
|
+
You are an agent setting up Oyster for a person. Start with a local desktop and
|
|
9
|
+
one working App. You need **Node 24 or newer and Git**, an internet connection
|
|
10
|
+
for the first install, and a browser to see the result. No Cloudflare account,
|
|
11
|
+
Docker or payment is needed for this trial.
|
|
12
|
+
|
|
13
|
+
## 1. Start Oyster
|
|
14
|
+
|
|
15
|
+
In the directory where the person wants to keep their project, check the tools:
|
|
55
16
|
|
|
56
17
|
```sh
|
|
57
18
|
node --version
|
|
58
|
-
pnpm --version
|
|
59
19
|
git --version
|
|
60
20
|
```
|
|
61
21
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
If it fails:
|
|
22
|
+
Expect Node `v24` or newer and a Git version. If either is missing or Node is
|
|
23
|
+
older, install it before continuing.
|
|
66
24
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- No pnpm, or an older version: install pnpm 11 with `npm install -g pnpm@11`.
|
|
70
|
-
|
|
71
|
-
## 2. Create a project
|
|
72
|
-
|
|
73
|
-
Make a new directory, install Oyster, its Computer and Wrangler, and copy the
|
|
74
|
-
example Worker out of the package. The local pnpm policy allows esbuild and
|
|
75
|
-
workerd to install their native binaries and disables unneeded optional
|
|
76
|
-
dependency scripts. Write it before installing so neither command stops for
|
|
77
|
-
unapproved build scripts:
|
|
25
|
+
Keep the next command running in a persistent terminal or your agent runtime's
|
|
26
|
+
managed process session:
|
|
78
27
|
|
|
79
28
|
```sh
|
|
80
|
-
|
|
81
|
-
cd my-oyster
|
|
82
|
-
cat > pnpm-workspace.yaml <<'YAML'
|
|
83
|
-
allowBuilds:
|
|
84
|
-
"@google/genai": false
|
|
85
|
-
"@mongodb-js/zstd": false
|
|
86
|
-
esbuild: true
|
|
87
|
-
exifreader: false
|
|
88
|
-
node-liblzma: false
|
|
89
|
-
protobufjs: false
|
|
90
|
-
workerd: true
|
|
91
|
-
YAML
|
|
92
|
-
pnpm add @fungi.computer/oyster @fungi.computer/computer react@^19.2.0 react-dom@^19.2.0
|
|
93
|
-
pnpm add -D wrangler
|
|
94
|
-
cp node_modules/@fungi.computer/oyster/examples/standalone/worker.ts .
|
|
95
|
-
cp node_modules/@fungi.computer/oyster/examples/standalone/wrangler.jsonc .
|
|
29
|
+
npx --yes @fungi.computer/oyster try --no-open
|
|
96
30
|
```
|
|
97
31
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
[Package versions in each Fungi release](https://docs.fungi.computer/reference/packages/#package-versions-in-each-fungi-release).
|
|
103
|
-
To install a specific release, name its versions, as in
|
|
104
|
-
[Upgrade Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/#upgrade-oyster).
|
|
105
|
-
|
|
106
|
-
Expected output: pnpm lists the added package after each `add`, and `ls` now
|
|
107
|
-
shows `node_modules`, `package.json`, `pnpm-workspace.yaml`, `worker.ts` and
|
|
108
|
-
`wrangler.jsonc`.
|
|
32
|
+
It creates `./my-oyster`, installs dependencies, starts Oyster on
|
|
33
|
+
`http://127.0.0.1:8787`, installs Hello and builds Tourtois, the desktop, from
|
|
34
|
+
its public source. `--no-open` lets you open the sign-in link yourself; omit it
|
|
35
|
+
on a person's computer to open their browser automatically.
|
|
109
36
|
|
|
110
|
-
|
|
111
|
-
otherwise.
|
|
37
|
+
On a fresh install, expect these phases, with timing and progress alongside:
|
|
112
38
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
pnpm store than your current default. Run the same `pnpm add` again with
|
|
121
|
-
`--store-dir` set to the store the error says the dependencies are linked
|
|
122
|
-
from; do not delete `node_modules` to get past it.
|
|
123
|
-
- `cp: cannot stat …/examples/standalone/…`: the install did not finish. Run
|
|
124
|
-
`pnpm add @fungi.computer/oyster @fungi.computer/computer react@^19.2.0 react-dom@^19.2.0`
|
|
125
|
-
again and read its first error.
|
|
126
|
-
|
|
127
|
-
## 3. Run a local Oyster
|
|
128
|
-
|
|
129
|
-
`worker.ts` and `wrangler.jsonc` are the whole Oyster. Run it under
|
|
130
|
-
`wrangler dev` on your machine, without its Computer container. Oyster serves an
|
|
131
|
-
HTTPS origin; `--local-upstream` presents your loopback requests to it at
|
|
132
|
-
`https://oyster.test`. Choose an owner key and keep this terminal open:
|
|
133
|
-
|
|
134
|
-
```sh
|
|
135
|
-
export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
|
|
136
|
-
export OYSTER_URL=http://127.0.0.1:8787
|
|
137
|
-
echo "$OYSTER_OWNER_KEY" > .oyster-owner-key
|
|
138
|
-
npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
|
|
139
|
-
--local-upstream oyster.test --upstream-protocol https \
|
|
140
|
-
--var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test
|
|
39
|
+
```text
|
|
40
|
+
Creating my-oyster
|
|
41
|
+
Installing dependencies with npm
|
|
42
|
+
Starting Oyster
|
|
43
|
+
Installing Hello and building Tourtois
|
|
44
|
+
Preparing desktop sign-in
|
|
45
|
+
Oyster is running
|
|
141
46
|
```
|
|
142
47
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
`
|
|
146
|
-
|
|
147
|
-
or Workers AI; steps 3 to 5 need none of them.
|
|
48
|
+
Then Oyster prints `Open (works once):` with a local sign-in URL, the Oyster
|
|
49
|
+
address, and paths to the owner key and Hello source. The key is saved in
|
|
50
|
+
`my-oyster/.oyster-owner`; it is never printed or put in the sign-in URL. Treat
|
|
51
|
+
the one-time URL and the key as credentials: do not put them in reports.
|
|
148
52
|
|
|
149
|
-
Keep
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```sh
|
|
153
|
-
export OYSTER_OWNER_KEY=$(cat .oyster-owner-key)
|
|
154
|
-
export OYSTER_URL=http://127.0.0.1:8787
|
|
155
|
-
curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/login
|
|
156
|
-
curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/api/installations
|
|
157
|
-
curl -s -H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/api/installations
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Expected output: `200`, then `401` (no key), then `[]` (no Apps installed yet).
|
|
53
|
+
Keep this terminal running while you use the desktop. If there is no success or
|
|
54
|
+
failure after five minutes, inspect the logs under `my-oyster/.oyster/` and
|
|
55
|
+
report the last phase; do not silently leave a stalled process running.
|
|
161
56
|
|
|
162
57
|
If it fails:
|
|
163
58
|
|
|
164
|
-
-
|
|
165
|
-
|
|
166
|
-
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
|
|
176
|
-
--local-upstream oyster.test --upstream-protocol https \
|
|
177
|
-
--var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test \
|
|
178
|
-
> oyster-dev.log 2>&1 &
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
To stop the server, press Ctrl-C in its terminal. A background server runs as
|
|
182
|
-
several processes (`npm exec`, `wrangler.js` and `workerd`); stop them all by
|
|
183
|
-
ending `wrangler.js`, then check that `/login` prints `000`:
|
|
184
|
-
|
|
185
|
-
```sh
|
|
186
|
-
pkill -f 'wrangler[.]js dev .*--port 8787'
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
## 4. Add an App
|
|
59
|
+
- **Port in use:** leave that listener alone. Follow the suggested command with
|
|
60
|
+
another port, such as `--port 8788`, and use the address Oyster prints.
|
|
61
|
+
- **Directory already has files:** choose a new directory with
|
|
62
|
+
`npx --yes @fungi.computer/oyster try another-oyster --no-open`. Do not delete
|
|
63
|
+
someone else's project.
|
|
64
|
+
- **Install or startup error:** read the diagnostic and the log path it names.
|
|
65
|
+
Keep the project, fix the reported cause and rerun the same command. Oyster
|
|
66
|
+
preserves your key and source; `--verbose` shows install and server logs.
|
|
67
|
+
- **Oyster needs desktop repair:** the host is available for recovery, but the
|
|
68
|
+
desktop is not ready. Follow the printed repair diagnostic and report it; this
|
|
69
|
+
is not a successful trial.
|
|
190
70
|
|
|
191
|
-
|
|
192
|
-
`fungi.app`. Make the smallest one, a single committed HTML page:
|
|
71
|
+
## 2. Open Hello
|
|
193
72
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
"name": "hello-app",
|
|
199
|
-
"private": true,
|
|
200
|
-
"fungi": { "app": { "displayName": "Hello", "capabilities": [] } }
|
|
201
|
-
}
|
|
202
|
-
EOF
|
|
203
|
-
cat > hello-app/bundle/index.html <<'EOF'
|
|
204
|
-
<!doctype html>
|
|
205
|
-
<title>Hello</title>
|
|
206
|
-
<h1>Hello from my first Oyster App</h1>
|
|
207
|
-
EOF
|
|
208
|
-
git -C hello-app init -q
|
|
209
|
-
git -C hello-app add .
|
|
210
|
-
git -C hello-app -c user.name=Oyster -c user.email=oyster@example.invalid \
|
|
211
|
-
commit -qm "Hello App"
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
Then pack that commit into a Release and install it as installation `hello` with
|
|
215
|
-
`@fungi.computer/oyster/pack`:
|
|
73
|
+
Open the printed one-time link in a browser on the same machine as Oyster. From
|
|
74
|
+
the Tourtois launcher, choose **Hello**. Success means the App visibly reads
|
|
75
|
+
**Hello from my first Oyster App**, without a loading or timeout overlay. An
|
|
76
|
+
HTTP 200 alone does not prove that the desktop or App opened.
|
|
216
77
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
import { tmpdir } from "node:os";
|
|
222
|
-
import { join, resolve } from "node:path";
|
|
223
|
-
import process from "node:process";
|
|
224
|
-
import { installRelease, packRelease } from "@fungi.computer/oyster/pack";
|
|
225
|
-
|
|
226
|
-
const source = resolve("hello-app");
|
|
227
|
-
const commit = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], {
|
|
228
|
-
encoding: "utf8",
|
|
229
|
-
}).trim();
|
|
230
|
-
const out = await mkdtemp(join(tmpdir(), "oyster-hello-"));
|
|
231
|
-
try {
|
|
232
|
-
await packRelease({
|
|
233
|
-
appId: "app_hello",
|
|
234
|
-
sourceDirectory: source,
|
|
235
|
-
sourceRevision: `git:${commit}`,
|
|
236
|
-
recipe: {
|
|
237
|
-
kind: "bundled-html",
|
|
238
|
-
entry: "bundle/index.html",
|
|
239
|
-
assets: {
|
|
240
|
-
maxManifestBytes: 65_536,
|
|
241
|
-
maxObjects: 16,
|
|
242
|
-
maxObjectBytes: 1_048_576,
|
|
243
|
-
maxTotalBytes: 4_194_304,
|
|
244
|
-
},
|
|
245
|
-
assetBase: "./",
|
|
246
|
-
backend: null,
|
|
247
|
-
maxOutputBytes: 4_194_304,
|
|
248
|
-
},
|
|
249
|
-
outDirectory: join(out, "release"),
|
|
250
|
-
});
|
|
251
|
-
const response = await installRelease({
|
|
252
|
-
directory: join(out, "release"),
|
|
253
|
-
url: process.env.OYSTER_URL,
|
|
254
|
-
key: process.env.OYSTER_OWNER_KEY,
|
|
255
|
-
installationId: "hello",
|
|
256
|
-
});
|
|
257
|
-
console.log(`installed hello: ${response.status} ${await response.text()}`);
|
|
258
|
-
} finally {
|
|
259
|
-
await rm(out, { recursive: true, force: true });
|
|
260
|
-
}
|
|
261
|
-
EOF
|
|
262
|
-
node install-hello.mjs
|
|
263
|
-
curl -s -o /dev/null -w '%{http_code}\n' \
|
|
264
|
-
-H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/apps/hello/
|
|
265
|
-
```
|
|
78
|
+
If the link has expired or was already used, open the printed Oyster address
|
|
79
|
+
with `/login` appended and paste the key from `my-oyster/.oyster-owner` into the
|
|
80
|
+
login form. If your agent cannot use a browser on that machine, give the person
|
|
81
|
+
these steps and report that the visible check is still unverified.
|
|
266
82
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
`"status":"enabled"`, then `200`. Running `node install-hello.mjs` again prints
|
|
270
|
-
`installed hello: 200`: the installation already exists, and Oyster switches it
|
|
271
|
-
to the Release just packed.
|
|
83
|
+
The local trial has no Computer, hosted git storage or Workers AI. Opening Hello
|
|
84
|
+
does not prove a cloud deployment or a model reply.
|
|
272
85
|
|
|
273
|
-
|
|
274
|
-
Hello from the installation list at `$OYSTER_URL/`.
|
|
86
|
+
## 3. Stop, restart and edit
|
|
275
87
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
server's. Set it from `.oyster-owner-key`.
|
|
280
|
-
- `fetch failed` or `ECONNREFUSED`: the server from step 3 is not running.
|
|
281
|
-
- The build reads committed files only. To install an edit, commit it in
|
|
282
|
-
`hello-app` and run `node install-hello.mjs` again; Oyster switches the
|
|
283
|
-
installation to the new Release and keeps its data.
|
|
284
|
-
|
|
285
|
-
An App with a backend, typed methods and its own SQLite adds
|
|
286
|
-
`fungi.backendDefinition` and a `backend` entry to its recipe. The
|
|
287
|
-
[Notes example App](https://github.com/fungi-computer/oyster/tree/main/examples/notes-app)
|
|
288
|
-
is one, and the Oyster README's "Pack an App" and "Build App Releases" sections
|
|
289
|
-
describe the recipe.
|
|
290
|
-
|
|
291
|
-
## 5. Connect over MCP
|
|
292
|
-
|
|
293
|
-
`/mcp` serves every installed App to MCP clients through one `execute` tool, in
|
|
294
|
-
which each App's methods are `env.<APP>`. The owner key signs in. For Claude
|
|
295
|
-
Code:
|
|
296
|
-
|
|
297
|
-
```sh
|
|
298
|
-
claude mcp add --transport http oyster "$OYSTER_URL/mcp" \
|
|
299
|
-
--header "Authorization: Bearer $OYSTER_OWNER_KEY"
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
To check `/mcp` without an MCP client, open a session and list its tools:
|
|
303
|
-
|
|
304
|
-
```sh
|
|
305
|
-
MCP=(-H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream')
|
|
306
|
-
SESSION=$(curl -s "${MCP[@]}" -D - -o /dev/null \
|
|
307
|
-
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
|
|
308
|
-
$OYSTER_URL/mcp | grep -i '^mcp-session-id' | cut -d' ' -f2 | tr -d '\r')
|
|
309
|
-
curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
|
|
310
|
-
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}' $OYSTER_URL/mcp
|
|
311
|
-
curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
|
|
312
|
-
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' $OYSTER_URL/mcp
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
Expected output: the last command prints an `event: message` block whose `data:`
|
|
316
|
-
line contains `"name":"execute"`.
|
|
317
|
-
|
|
318
|
-
If it fails:
|
|
319
|
-
|
|
320
|
-
- `SESSION` is empty: the `initialize` call was refused. Check the key as in
|
|
321
|
-
step 3.
|
|
322
|
-
- The copied Worker already includes `POST /api/keys`. Use the owner key to
|
|
323
|
-
create a separate key for each agent; no extra Worker is needed.
|
|
324
|
-
|
|
325
|
-
## 6. Add Git
|
|
326
|
-
|
|
327
|
-
Git is already part of the host: people and agents `clone`, `fetch` and `push`
|
|
328
|
-
App repositories with ordinary `git` at `/git/<installation>/<repo>.git`, with
|
|
329
|
-
repositories in Cloudflare Artifacts. Artifacts runs only once the Worker is
|
|
330
|
-
deployed in step 7. There, give each agent its own key:
|
|
88
|
+
Press Ctrl-C in the terminal that owns this trial to stop it. In an agent
|
|
89
|
+
runtime, stop your managed session and its children; do not kill processes by a
|
|
90
|
+
shared name or port. From the **same parent directory** as step 1, restart:
|
|
331
91
|
|
|
332
92
|
```sh
|
|
333
|
-
|
|
334
|
-
-H 'content-type: application/json' \
|
|
335
|
-
-d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
|
|
336
|
-
$OYSTER_URL/api/keys
|
|
93
|
+
npx --yes @fungi.computer/oyster try my-oyster --no-open
|
|
337
94
|
```
|
|
338
95
|
|
|
339
|
-
|
|
340
|
-
once; that key signs in to `git` and to `/mcp`.
|
|
341
|
-
|
|
342
|
-
## 7. Deploy to Cloudflare Workers
|
|
343
|
-
|
|
344
|
-
This step needs a Cloudflare account on Workers Paid with Containers, Artifacts,
|
|
345
|
-
Workers AI and Workflows enabled, and Docker running on this machine. Ask the
|
|
346
|
-
person before you deploy anything.
|
|
347
|
-
|
|
348
|
-
`wrangler.jsonc` names the Worker `oyster`, its R2 bucket `oyster-releases` and
|
|
349
|
-
its Artifacts namespace `oyster`. The Worker's address is
|
|
350
|
-
`https://oyster.<your-subdomain>.workers.dev`, or a custom domain:
|
|
96
|
+
Or, from **inside `my-oyster`**, run:
|
|
351
97
|
|
|
352
98
|
```sh
|
|
353
|
-
npx
|
|
354
|
-
npx wrangler r2 bucket create oyster-releases
|
|
355
|
-
export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
|
|
356
|
-
npx wrangler deploy --var OYSTER_ORIGIN:$OYSTER_URL
|
|
357
|
-
printf '%s' "$OYSTER_OWNER_KEY" | npx wrangler secret put OYSTER_OWNER_KEY
|
|
99
|
+
npx --yes @fungi.computer/oyster try . --no-open
|
|
358
100
|
```
|
|
359
101
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
102
|
+
Use the directory and `--port` you chose if they differ. Expect
|
|
103
|
+
`Restarting the Oyster in …`, then `Installing Hello and checking Tourtois`,
|
|
104
|
+
followed by a new sign-in link. Your owner key and Hello source stay in place.
|
|
363
105
|
|
|
364
|
-
|
|
365
|
-
|
|
106
|
+
To make the first edit, change the heading in
|
|
107
|
+
`my-oyster/hello-app/bundle/index.html`. Keep the `main.js` script: it tells
|
|
108
|
+
Oyster that the App is ready. Save it, then from the **parent directory** commit
|
|
109
|
+
the change in the `hello-app` Git repository:
|
|
366
110
|
|
|
367
111
|
```sh
|
|
368
|
-
|
|
112
|
+
git -C my-oyster/hello-app add bundle/index.html
|
|
113
|
+
git -C my-oyster/hello-app -c user.name="Oyster learner" \
|
|
114
|
+
-c user.email="oyster@example.invalid" commit -m "Edit Hello"
|
|
369
115
|
```
|
|
370
116
|
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
-
|
|
394
|
-
the
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
117
|
+
Expect a commit summary with one changed file. This example supplies an identity
|
|
118
|
+
for just this commit, so it also works on a machine without global Git settings.
|
|
119
|
+
Use your own name and email if you prefer. Adjust `my-oyster` if you chose
|
|
120
|
+
another project directory.
|
|
121
|
+
|
|
122
|
+
Stop and restart Oyster as above. It builds committed source; saving or
|
|
123
|
+
refreshing alone does not install an edit. Open the new sign-in link and choose
|
|
124
|
+
Hello again to check the changed heading.
|
|
125
|
+
|
|
126
|
+
The [build-an-App recipe](https://docs.fungi.computer/agents/build-an-app.md)
|
|
127
|
+
has exact edit commands and the next App to build.
|
|
128
|
+
|
|
129
|
+
## After the local trial
|
|
130
|
+
|
|
131
|
+
Stop here unless the person wants the next step. These are separate tasks:
|
|
132
|
+
|
|
133
|
+
- **Connect MCP:** use the
|
|
134
|
+
[MCP guide](https://docs.fungi.computer/oyster/concepts/#connect-an-agent-over-mcp)
|
|
135
|
+
for the `/mcp` endpoint and authentication. For this trial, use the printed
|
|
136
|
+
local Oyster address and the owner key in `my-oyster/.oyster-owner`. Hello is
|
|
137
|
+
a static page; connecting MCP does not give it backend methods.
|
|
138
|
+
- **Build another App:** follow the
|
|
139
|
+
[build-an-App recipe](https://docs.fungi.computer/agents/build-an-app.md),
|
|
140
|
+
then the [App guide](https://docs.fungi.computer/apps/) for backends and typed
|
|
141
|
+
methods.
|
|
142
|
+
- **Deploy:** follow
|
|
143
|
+
[Run your own Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/#deploy-it).
|
|
144
|
+
That step needs your own Cloudflare account, paid resources and Docker for the
|
|
145
|
+
Computer image. Do it only when the person asks for hosting.
|
|
146
|
+
|
|
147
|
+
For manual setup, the ordinary
|
|
148
|
+
[quickstart](https://docs.fungi.computer/oyster/quickstart/) keeps the Wrangler
|
|
149
|
+
commands under **What it does under the hood**. The
|
|
150
|
+
[Oyster concepts](https://docs.fungi.computer/oyster/concepts/) and
|
|
151
|
+
[API reference](https://docs.fungi.computer/oyster/api/) cover custom hosts,
|
|
152
|
+
packing Releases and Git integration.
|