@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/site/agent-quickstart.mdx

@@ -0,0 +1,346 @@
+---
+title: Agent quick start
+description:
+  Hand this guide to a coding agent to install Oyster from npm, run it locally,
+  install an App, connect over MCP and deploy.
+---
+
+You are an agent setting up Oyster for a person. Follow these steps in order.
+Run every command exactly as written, from the directory each step names.
+Compare its output with the expected output before you go on. When a step fails,
+read the "If it fails" notes under it before trying anything else.
+
+## What Oyster is
+
+- Oyster hosts Apps on one Cloudflare Worker, or on celld, a Workers-compatible
+  runtime you host yourself.
+- Each App is an immutable Release built from an exact git commit. Its backend
+  runs in its own Durable Object with its own SQLite, and it gets only the
+  bindings it declares.
+- People use Apps in a browser. Agents call the same App methods over HTTP or
+  through one MCP endpoint, `/mcp`.
+
+## 1. Check prerequisites
+
+You need Node 24 or newer, pnpm, Git, curl and openssl. You do not need a
+Cloudflare account until step 7. Docker is needed only in step 7, where Wrangler
+builds the Computer's container image.
+
+```sh
+node --version
+pnpm --version
+git --version
+```
+
+Expected output: a `v24.` or later Node version, any pnpm version, then any
+`git version 2.x` line.
+
+If it fails:
+
+- Wrong Node: install Node 24 with your version manager, for example
+  `mise use node@24` or `nvm install 24`.
+- No pnpm: run `corepack enable`, or use `npm install` wherever this guide says
+  `pnpm add`.
+
+## 2. Create a project
+
+Make a new directory, install Oyster, its Computer and Wrangler, and copy the
+example Worker out of the package:
+
+```sh
+mkdir my-oyster
+cd my-oyster
+pnpm add @fungi.computer/oyster @fungi.computer/computer
+pnpm add -D wrangler
+cp node_modules/@fungi.computer/oyster/examples/standalone/worker.ts .
+cp node_modules/@fungi.computer/oyster/examples/standalone/wrangler.jsonc .
+```
+
+Expected output: pnpm lists the added package after each `add`, and `ls` now
+shows `node_modules`, `package.json`, `worker.ts` and `wrangler.jsonc`.
+
+Every later command runs from this `my-oyster` directory unless the step says
+otherwise.
+
+If it fails:
+
+- `ERR_PNPM_IGNORED_BUILDS` naming packages such as `esbuild`, `workerd` or
+  `protobufjs`: pnpm installed them without running their install scripts, and
+  nothing in this guide needs those scripts. Go on.
+- `cp: cannot stat …/examples/standalone/…`: the install did not finish. Run
+  `pnpm add @fungi.computer/oyster @fungi.computer/computer` again and read its
+  first error.
+
+## 3. Run a local Oyster
+
+`worker.ts` and `wrangler.jsonc` are the whole Oyster. Run it under
+`wrangler dev` on your machine, without its Computer container. Oyster serves an
+HTTPS origin; `--local-upstream` presents your loopback requests to it at
+`https://oyster.test`. Choose an owner key and keep this terminal open:
+
+```sh
+export OYSTER_OWNER_KEY=$(openssl rand -hex 24)
+export OYSTER_URL=http://127.0.0.1:8787
+echo "$OYSTER_OWNER_KEY" > .oyster-owner-key
+npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
+  --local-upstream oyster.test --upstream-protocol https \
+  --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test
+```
+
+Expected output: warnings that the AI and Artifacts bindings reach remote
+resources, a bindings table listing `env.REGISTRY (OysterRegistry)`,
+`env.INSTANCES (StandaloneInstance)`, `env.COMPUTER (ComputerDO)` and the rest,
+then `Ready on http://127.0.0.1:8787`. Locally there is no Computer, git storage
+or Workers AI; steps 3 to 5 need none of them.
+
+Keep it running. Open a second terminal in `my-oyster`, set the same two
+variables there, and check that Oyster answers:
+
+```sh
+export OYSTER_OWNER_KEY=$(cat .oyster-owner-key)
+export OYSTER_URL=http://127.0.0.1:8787
+curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/login
+curl -s -o /dev/null -w '%{http_code}\n' $OYSTER_URL/api/installations
+curl -s -H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/api/installations
+```
+
+Expected output: `200`, then `401` (no key), then `[]` (no Apps installed yet).
+
+If it fails:
+
+- `Address already in use`: another process holds port 8787. Pick another port
+  and use it in both `--port` and `OYSTER_URL`.
+- `curl` prints `000`: the server is not ready yet. Wait for the `Ready on`
+  line.
+- `401` with the key: the two terminals hold different keys. Set
+  `OYSTER_OWNER_KEY` from `.oyster-owner-key` in both.
+- An agent runtime that cannot keep a process in the foreground starts the same
+  command in the background with its output in a log, then waits until the
+  `/login` check prints `200`:
+
+  ```sh
+  npx wrangler dev --local --enable-containers=false --ip 127.0.0.1 --port 8787 \
+    --local-upstream oyster.test --upstream-protocol https \
+    --var OYSTER_OWNER_KEY:$OYSTER_OWNER_KEY --var OYSTER_ORIGIN:https://oyster.test \
+    > oyster-dev.log 2>&1 &
+  ```
+
+To stop the server, press Ctrl-C in its terminal. A background server runs as
+several processes (`npm exec`, `wrangler.js` and `workerd`); stop them all by
+ending `wrangler.js`, then check that `/login` prints `000`:
+
+```sh
+pkill -f 'wrangler[.]js dev .*--port 8787'
+```
+
+## 4. Add an App
+
+An App is a git repository with a `package.json` that declares it under
+`fungi.app`. Make the smallest one, a single committed HTML page:
+
+```sh
+mkdir -p hello-app/bundle
+cat > hello-app/package.json <<'EOF'
+{
+  "name": "hello-app",
+  "private": true,
+  "fungi": { "app": { "displayName": "Hello", "capabilities": [] } }
+}
+EOF
+cat > hello-app/bundle/index.html <<'EOF'
+<!doctype html>
+<title>Hello</title>
+<h1>Hello from my first Oyster App</h1>
+EOF
+git -C hello-app init -q
+git -C hello-app add .
+git -C hello-app -c user.name=Oyster -c user.email=oyster@example.invalid \
+  commit -qm "Hello App"
+```
+
+Then pack that commit into a Release and install it as installation `hello` with
+`@fungi.computer/oyster/pack`:
+
+```sh
+cat > install-hello.mjs <<'EOF'
+import { execFileSync } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { installRelease, packRelease } from "@fungi.computer/oyster/pack";
+
+const source = resolve("hello-app");
+const commit = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], {
+  encoding: "utf8",
+}).trim();
+const out = await mkdtemp(join(tmpdir(), "oyster-hello-"));
+try {
+  await packRelease({
+    appId: "app_hello",
+    sourceDirectory: source,
+    sourceRevision: `git:${commit}`,
+    recipe: {
+      kind: "bundled-html",
+      entry: "bundle/index.html",
+      assets: {
+        maxManifestBytes: 65_536,
+        maxObjects: 16,
+        maxObjectBytes: 1_048_576,
+        maxTotalBytes: 4_194_304,
+      },
+      assetBase: "./",
+      backend: null,
+      maxOutputBytes: 4_194_304,
+    },
+    outDirectory: join(out, "release"),
+  });
+  const response = await installRelease({
+    directory: join(out, "release"),
+    url: process.env.OYSTER_URL,
+    key: process.env.OYSTER_OWNER_KEY,
+    installationId: "hello",
+  });
+  console.log(`installed hello: ${response.status} ${await response.text()}`);
+} finally {
+  await rm(out, { recursive: true, force: true });
+}
+EOF
+node install-hello.mjs
+curl -s -o /dev/null -w '%{http_code}\n' \
+  -H "Authorization: Bearer $OYSTER_OWNER_KEY" $OYSTER_URL/apps/hello/
+```
+
+Expected output: one line starting
+`installed hello: 201 {"installationId":"hello",` and containing
+`"status":"enabled"`, then `200`. Running `node install-hello.mjs` again prints
+`installed hello: 200`: the installation already exists, and Oyster switches it
+to the Release just packed.
+
+A person can open `$OYSTER_URL/login`, sign in with the owner key, and open
+Hello from the installation list at `$OYSTER_URL/`.
+
+If it fails:
+
+- `installed hello: 401`: `OYSTER_OWNER_KEY` in this terminal differs from the
+  server's. Set it from `.oyster-owner-key`.
+- `fetch failed` or `ECONNREFUSED`: the server from step 3 is not running.
+- The build reads committed files only. To install an edit, commit it in
+  `hello-app` and run `node install-hello.mjs` again; Oyster switches the
+  installation to the new Release and keeps its data.
+
+An App with a backend, typed methods and its own SQLite adds
+`fungi.backendDefinition` and a `backend` entry to its recipe. The
+[Notes example App](https://github.com/fungi-computer/oyster/tree/main/examples/notes-app)
+is one, and the Oyster README's "Pack an App" and "Build App Releases" sections
+describe the recipe.
+
+## 5. Connect over MCP
+
+`/mcp` serves every installed App to MCP clients through one `execute` tool, in
+which each App's methods are `env.<APP>`. The owner key signs in. For Claude
+Code:
+
+```sh
+claude mcp add --transport http oyster "$OYSTER_URL/mcp" \
+  --header "Authorization: Bearer $OYSTER_OWNER_KEY"
+```
+
+To check `/mcp` without an MCP client, open a session and list its tools:
+
+```sh
+MCP=(-H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream')
+SESSION=$(curl -s "${MCP[@]}" -D - -o /dev/null \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
+  $OYSTER_URL/mcp | grep -i '^mcp-session-id' | cut -d' ' -f2 | tr -d '\r')
+curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' $OYSTER_URL/mcp
+curl -s "${MCP[@]}" -H "mcp-session-id: $SESSION" -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' $OYSTER_URL/mcp
+```
+
+Expected output: the last command prints an `event: message` block whose `data:`
+line contains `"name":"execute"`.
+
+If it fails:
+
+- `SESSION` is empty: the `initialize` call was refused. Check the key as in
+  step 3.
+- Named keys for each agent (`POST /api/keys`) come with the Git worker in
+  step 6. The plain standalone Worker answers `404` there.
+
+## 6. Add Git
+
+Git is already part of the host: people and agents `clone`, `fetch` and `push`
+App repositories with ordinary `git` at `/git/<installation>/<repo>.git`, with
+repositories in Cloudflare Artifacts. Artifacts runs only once the Worker is
+deployed in step 7. There, give each agent its own key:
+
+```sh
+curl -s -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
+  $OYSTER_URL/api/keys
+```
+
+Expected output: JSON with a `plaintext` field starting `oyk_`. Oyster shows it
+once; that key signs in to `git` and to `/mcp`.
+
+## 7. Deploy to Cloudflare Workers
+
+This step needs a Cloudflare account on Workers Paid with Containers, Artifacts,
+Workers AI and Workflows enabled, and Docker running on this machine. Ask the
+person before you deploy anything.
+
+`wrangler.jsonc` names the Worker `oyster`, its R2 bucket `oyster-releases` and
+its Artifacts namespace `oyster`. The Worker's address is
+`https://oyster.<your-subdomain>.workers.dev`, or a custom domain:
+
+```sh
+npx wrangler login
+npx wrangler r2 bucket create oyster-releases
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+npx wrangler deploy --var OYSTER_ORIGIN:$OYSTER_URL
+printf '%s' "$OYSTER_OWNER_KEY" | npx wrangler secret put OYSTER_OWNER_KEY
+```
+
+Expected output: `wrangler deploy` builds the Computer image, uploads it and
+prints the deployed `https://` URL, and `wrangler secret put` reports the secret
+uploaded.
+
+Then install Fungi's seven starter Apps, each built on this Oyster's Computer
+from its own repository:
+
+```sh
+npx oyster install-apps
+```
+
+Expected output: a `source recorded` line per App, `Building … on the Computer`
+and `Installed …` lines (two builds at a time, Tourtois first), a timing table,
+and `Installed 7 Apps`. Open `$OYSTER_URL/login` with the owner key to see the
+Tourtois desktop.
+
+To keep `OYSTER_ORIGIN` across later deploys, set `vars.OYSTER_ORIGIN` in
+`wrangler.jsonc`; every deploy replaces the Worker's variables.
+
+If it fails:
+
+- `R2 bucket … already exists`: use that bucket, or pick a new name and put it
+  in `wrangler.jsonc`.
+- A secret prompt on stdin: pipe the key as shown; never type it into a log.
+- Bindings or migrations refused: deploy the copied `wrangler.jsonc` unchanged
+  except for `vars` and the bucket name.
+- `docker` not found or not running: start Docker; Wrangler builds the Computer
+  image from `node_modules/@fungi.computer/computer/Dockerfile`.
+- A build `failed` in `install-apps`: run it again; finished Apps are kept and
+  replaced in place.
+
+## Where to go next
+
+- The Oyster README (`node_modules/@fungi.computer/oyster/README.md`) explains
+  the host, Apps, capabilities, MCP and the shell in depth.
+- [oyster.shiit.app](https://oyster.shiit.app/) runs this same host with the
+  seven starter Apps.
+- Oyster is built from the other Fungi packages, each its own repository under
+  [github.com/fungi-computer](https://github.com/fungi-computer) and on npm as
+  `@fungi.computer/<name>`. The README's "Part of Fungi" section lists them.

package/examples/standalone/worker.ts

@@ -0,0 +1,7 @@
+// The whole Oyster: Apps installed from Releases, each with its own Durable
+// Object and SQLite; git through Artifacts; a Computer in a Cloudflare
+// Container that builds App sources and runs terminals and files; Agents on
+// Workers AI; Workflows; and media. Runs on Cloudflare Workers
+// (`wrangler deploy`) and on celld from the same code.
+export * from "@fungi.computer/oyster/standalone";
+export { default } from "@fungi.computer/oyster/standalone";

package/examples/standalone/wrangler.jsonc

@@ -0,0 +1,82 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  // The whole Oyster. Copy it beside worker.ts, set OYSTER_ORIGIN, and deploy.
+  "name": "oyster",
+  "main": "worker.ts",
+  "compatibility_date": "2026-09-04",
+  "compatibility_flags": ["nodejs_compat"],
+  "workers_dev": true,
+  "preview_urls": false,
+  "observability": { "enabled": true },
+  "workflows": [
+    {
+      "binding": "GRAPH_WORKFLOWS",
+      "name": "oyster-graphs",
+      "class_name": "StandaloneGraphWorkflow",
+    },
+  ],
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "containers": [
+    {
+      "class_name": "ComputerDO",
+      "image": "./node_modules/@fungi.computer/computer/Dockerfile",
+      "instance_type": "standard-4",
+      "max_instances": 1,
+      "rollout_active_grace_period": 0,
+      "rollout_step_percentage": [100],
+    },
+  ],
+  "ai": { "binding": "AI" },
+  "images": { "binding": "IMAGES" },
+  "r2_buckets": [
+    { "binding": "RELEASES", "bucket_name": "oyster-releases" },
+    { "binding": "APP_ARTIFACTS", "bucket_name": "oyster-releases" },
+  ],
+  "artifacts": [{ "binding": "ARTIFACTS", "namespace": "oyster" }],
+  "vars": {
+    "OYSTER_COMPUTER_ID": "workspace",
+    "OYSTER_HOME_INSTALLATION": "tourtois",
+    "OYSTER_ORIGIN": "https://oyster.example",
+    "OYSTER_OWNER_NAME": "owner",
+    // Names the AI Gateway that Prints' third-party models (GPT Image 2,
+    // Seedance, Veo) and the background media retry owner route through.
+    // Not a secret: Cloudflare creates the gateway by this id on first use.
+    "AI_GATEWAY_ID": "oyster",
+  },
+  "durable_objects": {
+    "bindings": [
+      { "name": "TENANTS", "class_name": "StandaloneTenants" },
+      { "name": "MCP", "class_name": "OysterMcp" },
+
+      { "name": "REGISTRY", "class_name": "OysterRegistry" },
+      { "name": "WORKFLOW_RUNS", "class_name": "StandaloneWorkflowRuns" },
+      { "name": "INSTANCES", "class_name": "StandaloneInstance" },
+      { "name": "COMPUTER", "class_name": "ComputerDO" },
+      { "name": "KEYS", "class_name": "OysterKeys" },
+      { "name": "WEBHOOKS", "class_name": "OysterWebhooks" },
+      { "name": "AGENTS", "class_name": "StandaloneAgent" },
+      { "name": "AGENT_DIRECTORY", "class_name": "AgentDirectory" },
+      { "name": "MEDIA_OPERATION", "class_name": "MediaOperationDO" },
+    ],
+  },
+  // One initial tag: pre-launch history was collapsed (Levi 10-14, data wipe
+  // authorized), so a fresh Worker creates every bound class at once.
+  "migrations": [
+    {
+      "tag": "oyster-v1",
+      "new_sqlite_classes": [
+        "StandaloneTenants",
+        "OysterMcp",
+        "OysterRegistry",
+        "StandaloneWorkflowRuns",
+        "StandaloneInstance",
+        "ComputerDO",
+        "OysterKeys",
+        "OysterWebhooks",
+        "StandaloneAgent",
+        "AgentDirectory",
+        "MediaOperationDO",
+      ],
+    },
+  ],
+}