BP reference update by codingfrog27 · Pull Request #413 · leaningtech/labs

codingfrog27 · 2026-05-18T09:58:28Z

Feedback implemented!

For consideration

for the optional disk image parameter i wrote

When specified, the pod's home filesystem will point to the /home directory within this image.

Is this correct? Or does the pod's home directory point to the root of the image instead?

changes

added base bp handle reference page with general info
same for terminal and process
- referenced these 3 where applicable
Documented Storagekey allowing for persitent storage
mentioned onopen maps to xdg-open
Tightened language throughout

Co-authored-by: Copilot <copilot@github.com>

cloudflare-workers-and-pages · 2026-05-18T09:59:07Z

Deploying labs-browserpod-previews with Cloudflare Pages

Latest commit:	`0ea495b`
Status:	✅ Deploy successful!
Preview URL:	https://0c8205d9.labs-browserpod-previews.pages.dev
Branch Preview URL:	https://browserpod-reference-updates.labs-browserpod-previews.pages.dev

View logs

GabrielaReyna

Good job documenting these!

In addition to my comments on the code, I will add some bullet points as to-do's:

Please document Terminal and Process, even if they are opaque or minimalistic. Please sync with Yuri and Alessandro for any questions. These are first-class, so they go at the same level as BinaryFile, TextFile etc.
Please add links where Terminal and Process are mentioned in the text, referring to their documented page.
There is a nice explanatory page for BinaryFile, this is a good chance to do something similar for BrowserPod in the reference, given an instance of BrowserPod we call it a "Pod" and it can be confusing for some users. This is an opportunity to link to this page when we call it like so.

…dle and process, and tightened langauge, sorted reference below demos

alexp-sssup · 2026-06-03T14:18:47Z

 - **nodeVersion (`string`, _optional_)** - The version of Node.js to use. Currently only "22" is allowed.
- **storageKey (`string`, _optional_)** - An arbitrary string used to support multiple pods on the same origin or multiple tabs in parallel. For example, `boot({ apiKey: "...", storageKey: "vite" })` and `boot({ apiKey: "...", storageKey: "app-12345" })` allocate two completely independent disks.
- **userImage (`string`, _optional_)** - A URL pointing to a custom WebAssembly binary to load into the pod environment. When specified, this WebAssembly module will be loaded and made available within the pod instead of using the default environment.
+- **storageKey (`string`, _optional_)** - An arbitrary string that identifies the pod's storage. Rebooting with the same key **resumes the same disk**, making the filesystem persistent across sessions. Using different keys gives each pod its own independent disk. For example, `boot({ apiKey: "...", storageKey: "my-project" })` always resumes the same environment, while `boot({ apiKey: "...", storageKey: "app-12345" })` uses a separate one.


The explanation does not clarify much. Both my-project and app-12345 would "resume from the same environment". This also does not explain properly our recent changes about "ephemeral" mode, which happens when no "storageKey" is passed.

alexp-sssup · 2026-06-03T14:19:22Z

- **storageKey (`string`, _optional_)** - An arbitrary string used to support multiple pods on the same origin or multiple tabs in parallel. For example, `boot({ apiKey: "...", storageKey: "vite" })` and `boot({ apiKey: "...", storageKey: "app-12345" })` allocate two completely independent disks.
- **userImage (`string`, _optional_)** - A URL pointing to a custom WebAssembly binary to load into the pod environment. When specified, this WebAssembly module will be loaded and made available within the pod instead of using the default environment.
+- **storageKey (`string`, _optional_)** - An arbitrary string that identifies the pod's storage. Rebooting with the same key **resumes the same disk**, making the filesystem persistent across sessions. Using different keys gives each pod its own independent disk. For example, `boot({ apiKey: "...", storageKey: "my-project" })` always resumes the same environment, while `boot({ apiKey: "...", storageKey: "app-12345" })` uses a separate one.
+- **userImage (`string`, _optional_)** - A URL pointing to a custom ext2 filesystem image to use as the pod's root filesystem. When specified, the pod's home directory will point to the `/home` directory within this image.


No, this is incorrect. The image is not the root. It's mounted directly on /home

alexp-sssup · 2026-06-03T14:20:31Z

 - **cols (`number`, _optional_)** - The number of columns (width) for the terminal display. If not specified, a default width will be used.
 - **rows (`number`, _optional_)** - The number of rows (height) for the terminal display. If not specified, a default height will be used.
- **onOutput** (`function(buffer: Uint8Array | ArrayBuffer, vt?: unknown) => void`) - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information.
+- **onOutput (`function(buffer: Uint8Array | ArrayBuffer, vt?: unknown) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information.


Wait, why would we send either Uint8Arrays or ArrayBuffer. We certainly send only one of these. Check the code please.

alexp-sssup · 2026-06-03T14:21:52Z

+
+## Notes
+
+`onOpen` maps to use of the [`xdg-open`](https://linux.die.net/man/1/xdg-open) utility.


Maybe "intercepts the use of" rather than "maps to use of"

alexp-sssup · 2026-06-03T14:22:38Z

 ## Returns

-`createFile` returns a [Promise] which is resolved when the operation has succeded. The promise resolves to a `BinaryFile` object if `mode="binary"`, and to a `TextFile` object if `mode="utf-8"`. If the file could not be created, the [Promise] will be rejected.
+`createFile` returns a [Promise] which resolves to a [BinaryFile] object if `mode="binary"`, and to a [TextFile] object if `mode="utf-8"`. If the file could not be created, the [Promise] will be rejected.


We should also specify that if the file exist it will be truncated to 0 length

alexp-sssup · 2026-06-03T14:23:36Z

+
+**"Isolated"** means each Pod is self-contained:
+
+- Files don't persist between Pods by default


Let's clarify here, it seems to conflate isolation between pods and persistence of the disk

alexp-sssup · 2026-06-03T14:24:16Z

+
+- Files don't persist between Pods by default
+- Processes in one Pod cannot access another
+- Nothing runs on a separate server, it's all client-side


Let's flip this, everything runs client-side, there is no server-side execution...

alexp-sssup · 2026-06-03T14:24:48Z

+
+A Pod is created with [`BrowserPod.boot`](./boot) and exists for the lifetime of the browser session. By default, Pods are **ephemeral** — closing the tab starts a fresh environment.
+
+To persist the filesystem across sessions, pass a `storageKey` to [`boot`](./boot). Rebooting with the same key resumes the same disk:


This is correct, but should be reflected in the storageKey docs

first draft

6b8ce2c

Co-authored-by: Copilot <copilot@github.com>

alexp-sssup requested changes May 18, 2026

View reviewed changes

Comment thread sites/browserpod/src/content/docs/13-reference/00-BrowserPod/00-boot.md Outdated

Comment thread sites/browserpod/src/content/docs/13-reference/00-BrowserPod/05-onOpen.md Outdated

GabrielaReyna changed the title ~~first draft~~ BP reference update (first draft) May 18, 2026

GabrielaReyna requested changes May 18, 2026

View reviewed changes

sort references alphabetically

767ce54

codingfrog27 force-pushed the Browserpod-reference-updates branch from 62acc57 to 99d3aa7 Compare June 3, 2026 14:00

codingfrog27 requested review from GabrielaReyna and alexp-sssup June 3, 2026 14:12

added storagekey for persistence, references for terminal, the bp han…

0ea495b

…dle and process, and tightened langauge, sorted reference below demos

codingfrog27 force-pushed the Browserpod-reference-updates branch from 99d3aa7 to 0ea495b Compare June 3, 2026 14:25

alexp-sssup requested changes Jun 3, 2026

View reviewed changes

codingfrog27 changed the title ~~BP reference update (first draft)~~ BP reference update Jun 4, 2026


		## Notes

		`onOpen` maps to use of the [`xdg-open`](https://linux.die.net/man/1/xdg-open) utility.


		"Isolated" means each Pod is self-contained:

		- Files don't persist between Pods by default


		A Pod is created with [`BrowserPod.boot`](./boot) and exists for the lifetime of the browser session. By default, Pods are ephemeral — closing the tab starts a fresh environment.

		To persist the filesystem across sessions, pass a `storageKey` to [`boot`](./boot). Rebooting with the same key resumes the same disk:

Conversation

codingfrog27 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

For consideration

changes

Uh oh!

cloudflare-workers-and-pages Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying labs-browserpod-previews with Cloudflare Pages

Uh oh!

Uh oh!

Uh oh!

GabrielaReyna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codingfrog27 commented May 18, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented May 18, 2026 •

edited

Loading