Add a Pyodide Python runtime for in-sandbox data analysis (numpy/pandas/openpyxl)

[NeilMazumdar]

Summary

Add an opt-in Pyodide-backed Python runtime so sandboxed code can import numpy, pandas, scipy, openpyxl — entirely in WASM, preserving the air-gapped, no-host-process posture (audit C1). Driven by integrating sql-fs as the code-execution sandbox behind a self-hosted LibreChat deployment, where the core use case is agents analysing user-uploaded CSV/Excel files.

A detailed implementation analysis (shared back by the maintainer) is attached as a comment below and is the accepted design for this issue.

Accepted design (per the attached analysis)

• New python_runtime: "stdlib" | "pyodide" field on sandbox create, replacing python: boolean (null = no Python). Breaking, major-version bump; spans the API + both SDKs + MCP tool + OpenAPI + DB migration (3 dialects) + skills docs.
• Pyodide registered as a customCommands python3 that shadows the built-in WASM CPython (bash.ts:499) — no just-bash fork required.
• File access via ctx.fs (async; removes the current 8 MB read cap); user code stays inside WASM (security posture unchanged).
• Resourcing: ~350–400 MB per exec; a separate MAX_CONCURRENT_PYODIDE (default 2 — do not reuse the stdlib cap of 5, or a 2 GB container OOMs); ~5–8 s cold start; new timeout env vars.
• Rollout as 2 PRs (API/SDK rename, then Pyodide implementation).

Requests from the integration (consumer) side

1. Output-file drain in v1. The analysis lists the file write-back strategy as an open question — but our use case frequently has the agent generate an output (e.g. a transformed .xlsx or chart), so please ensure files written by the script are drained back to SqlFs and retrievable within v1, not just input loading.
2. Confirm the MCP field name. We'll call sandbox_create over MCP with python_runtime: "pyodide" — please confirm that's the final field/value so we can pin our integration against it.
3. Version pin. As a breaking (major) change, we'll pin our LibreChat integration to the release that ships the Pyodide implementation PR.

Our deployment context (FYI for sizing)

Hosting sql-fs on Azure Container Apps + Postgres, with private/internal ingress. Per the analysis we'll plan a 4 GB container and MAX_CONCURRENT_PYODIDE=2.

Acceptance criteria (consumer view)

• A python_runtime: "pyodide" sandbox can import pandas, numpy, openpyxl, read an uploaded .xlsx/.csv, compute an aggregate, and write an output file that is retrievable — all in-WASM, no host process, no network.
• The stdlib runtime path remains available and unchanged.
• Resource/concurrency knobs are documented.

Relationship to other work

Independent of and parallelizable with #117 (MCP static-header auth) — different code path (sandbox runtime vs MCP auth middleware), no logical dependency. #117 is the gating item for the integration (it's what lets the client connect); this Pyodide work is the data-science enhancement on top.

[NeilMazumdar]

Maintainer's implementation analysis (shared back), attached for reference. This is the accepted design referenced in the issue body above.

---

Pyodide Runtime Proposal — Detailed Analysis

Context: evaluating the GitHub issue draft (sql-fs-pyodide-runtime-github-issue.md) against the
current codebase. Goal: understand what needs to change, what the risks are, and what the
implementation path looks like.

1. What the proposal asks for

A python_runtime field on sandbox create that replaces the existing python: boolean flag:

python_runtime	Behaviour
undefined / omitted	No Python — python3 command absent
"stdlib"	Current WASM CPython, stdlib only, ~1.5 s cold start, 8 MB file limit
"pyodide"	Pyodide WASM, numpy/pandas/scipy/openpyxl, ~5–8 s cold start, no file limit

The python: boolean field is removed from the API. Callers that previously passed
python: true pass python_runtime: "stdlib" instead.

Goals:

• Registers a Pyodide-backed python3 custom command only for that sandbox
• Gives Python code access to numpy, pandas, scipy, openpyxl — all in WASM
• Preserves the air-gapped, no-host-process security posture (audit C1)

Secondary ask: static-header / API-key auth for LibreChat's MCP client. That is
independent and not covered here.

---

2. Why the custom-command path works

just-bash registers customCommands after built-ins and explicitly lets them override
built-ins with the same name (bash.ts:499):

// Register custom commands (after built-ins so they can override)
if (options.customCommands) {
  for (const cmd of options.customCommands) { ... }
}

So a custom command named python3 will shadow just-bash's WASM CPython for that Bash
instance. No fork of just-bash is needed.

The CommandContext interface gives the command everything it needs:

Field	Use
ctx.fs.readFile(path)	Read files from SqlFs into Pyodide FS — no 8 MB cap (plain async Node.js)
ctx.fs.resolvePath(ctx.cwd, arg)	Resolve the script path argument
ctx.stdin	Forward stdin bytes into Pyodide
ctx.cwd	Set Pyodide's working directory

---

3. How the filesystem works differently

Current stdlib python3:

SqlFs ──► SharedArrayBuffer IPC (8 MB cap) ──► HOSTFS bridge ──► Emscripten FS ──► open()

Files are bridged lazily on every open() call, limited to 8 MB per read.

Proposed Pyodide custom command:

SqlFs ──► ctx.fs.readFile() [async Node.js, no cap] ──► pyodide.FS.writeFile() ──► Emscripten FS ──► open()

Files are copied explicitly into Pyodide's in-memory Emscripten FS before the script runs.
The 8 MB limit is gone entirely. The tradeoff: all files needed by the script are loaded into
the Pyodide heap upfront rather than lazily — higher peak memory for large files.

The command implementation would:

1. Read every file under the sandbox root via ctx.fs.readFile() (or lazily on demand — TBD)
2. Write them into pyodide.FS at the same paths
3. Run the user script via await pyodide.runPythonAsync(code)
4. Drain any written/modified files back to SqlFs after the script exits

---

4. Changes required in this repo

4.1 src/sql-fs/types.ts — SandboxMeta / SandboxListEntry

Replace python: boolean with pythonRuntime:

export type PythonRuntime = "stdlib" | "pyodide";

export interface SandboxMeta {
  readonly owner: string | null;
  readonly name: string | null;
  readonly pythonRuntime: PythonRuntime | null;  // null = no Python
  readonly javascript: boolean;
  readonly network: boolean;
  readonly createdAt?: string;
}

export interface SandboxListEntry {
  readonly id: string;
  readonly name: string | null;
  readonly owner: string | null;
  readonly createdAt: Date;
  readonly pythonRuntime: PythonRuntime | null;
  readonly javascript: boolean;
  readonly network: boolean;
}

python: boolean is removed entirely from both interfaces.

4.2 src/api/routes/sandboxes.ts — create body schema

Replace python: boolean with python_runtime in the Zod schema:

const createBodySchema = z.object({
  name: z.string().max(255).optional(),
  env: z.record(z.string()).optional(),
  files: z.record(z.string()).optional(),
  python_runtime: z.enum(["stdlib", "pyodide"]).optional(),  // replaces python: boolean
  javascript: z.boolean().optional(),
  network: z.boolean().optional(),
});

python: boolean is removed from the schema. The response body also drops python and
returns python_runtime instead:

{ "id": "...", "python_runtime": "pyodide", "javascript": false, "network": false }

4.3 src/api/session-manager.ts — RuntimeOptions + session creation

Replace python: boolean in RuntimeOptions with pythonRuntime:

export interface RuntimeOptions {
  readonly pythonRuntime: PythonRuntime | null;  // null = no Python
  readonly javascript: boolean;
  readonly network: boolean;
}

const DEFAULT_RUNTIME_OPTIONS: RuntimeOptions = {
  pythonRuntime: null,
  javascript: false,
  network: false,
};

In session creation (around line 478), derive python for just-bash and conditionally
register the Pyodide command:

const customCommands = [
  ...(resolvedRuntime.javascript ? [nodeCommand] : []),
  ...(resolvedRuntime.pythonRuntime === "pyodide" ? [pyodideCommand] : []),
];

const bash = new Bash({
  fs,
  // just-bash still takes python: boolean — set true for either runtime
  python: resolvedRuntime.pythonRuntime !== null || undefined,
  javascript: resolvedRuntime.javascript || undefined,
  network: resolvedRuntime.network ? { dangerouslyAllowFullInternetAccess: true } : undefined,
  defenseInDepth: defenseInDepthConfig,
  customCommands: customCommands.length > 0 ? customCommands : undefined,
});

When pythonRuntime === "pyodide", the pyodideCommand shadows just-bash's built-in
python3 — Pyodide handles execution, the built-in WASM CPython never runs.

Add a separate pyodideSem semaphore alongside pythonSem and jsSem:

this.pyodideSem = {
  limit: maxConcurrentPyodide ?? Number(process.env.MAX_CONCURRENT_PYODIDE ?? "2"),
  maxWaiters: ...,
  waitTimeoutMs: ...,
  inFlight: 0,
  waiters: [],
};

Pyodide needs a lower concurrency cap than stdlib Python — see resource section below.

4.4 src/api/commands/pyodide-command.ts — new file

The custom command itself. Rough shape:

import { defineCommand } from "just-bash";
import { loadPyodide } from "pyodide";  // npm: pyodide

export const pyodideCommand = defineCommand("python3", async (args, ctx) => {
  // Acquire pyodideSem before loading Pyodide (heavy)
  // ...

  const pyodide = await loadPyodide({ /* no indexURL fetch — pre-bundled */ });

  // Mount sandbox FS into Pyodide
  const allPaths = await ctx.fs.getAllPaths?.() ?? [];
  for (const path of allPaths) {
    const content = await ctx.fs.readFile(path);
    ensureDir(pyodide, dirname(path));
    pyodide.FS.writeFile(path, content);
  }

  // Resolve script
  const scriptPath = ctx.fs.resolvePath(ctx.cwd, args[0] ?? "");
  const code = pyodide.FS.readFile(scriptPath, { encoding: "utf8" });

  // Capture stdout/stderr
  let stdout = "";
  let stderr = "";
  pyodide.setStdout({ batched: (s) => { stdout += s + "\n"; } });
  pyodide.setStderr({ batched: (s) => { stderr += s + "\n"; } });

  let exitCode = 0;
  try {
    await pyodide.runPythonAsync(code);
  } catch (e) {
    stderr += String(e) + "\n";
    exitCode = 1;
  }

  // Drain written files back to SqlFs
  // (files modified inside Pyodide FS need to be written back)
  // ...

  return { stdout, stderr, exitCode };
});

4.5 DB schema — sandboxes table

Replace the python boolean column with a python_runtime varchar column (nullable —
null means no Python). Needs a migration for each dialect (postgres, mysql, azure-sql):

-- postgres example
ALTER TABLE sandboxes DROP COLUMN python;
ALTER TABLE sandboxes ADD COLUMN python_runtime varchar(16) NULL
  CHECK (python_runtime IN ('stdlib', 'pyodide'));

Existing rows get python_runtime = NULL (no Python) after the migration — which is
correct since the old python = false default means Python was not enabled.

4.6 CLAUDE.md env table

New env vars to document:

Variable	Default	Description
MAX_CONCURRENT_PYODIDE	2	Max concurrent Pyodide executions
PYODIDE_QUEUE_TIMEOUT_MS	120000	How long a Pyodide exec can wait for a slot
PYODIDE_EXEC_TIMEOUT_MS	60000	Max wall-clock time for a single Pyodide script

---

5. Resource constraints and sizing

This is the hardest part of the proposal.

Memory per worker

Runtime	Approx. heap per execution
stdlib python3	~80 MB
js-exec (QuickJS)	~64 MB
Pyodide (no packages)	~150 MB
Pyodide + numpy	~250 MB
Pyodide + numpy + pandas	~350–400 MB

At MAX_CONCURRENT_PYODIDE=2 on the current 2 GB ACA container:

• 2 × 400 MB Pyodide = 800 MB
• Plus the Node.js process baseline (~200 MB), active stdlib Python workers, and OS overhead
• Leaves ~800 MB for everything else — tight but workable at concurrency=2

At MAX_CONCURRENT_PYODIDE=5 (matching current Python cap): 5 × 400 MB = 2 GB for Pyodide
alone. The container would OOM. Do not reuse MAX_CONCURRENT_PYTHON for Pyodide.

Recommendation: start at MAX_CONCURRENT_PYODIDE=2, monitor, and increase the ACA container
to 4 GB if Pyodide adoption grows.

Cold start

Runtime	First exec
stdlib python3	~1.5 s
Pyodide (no packages)	~2–3 s
Pyodide + full package load	~5–8 s

The loadPyodide() call initialises the WASM binary and mounts the stdlib. Package imports
(import pandas) add time on first use within a session. A warm Pyodide worker pool (reusing
the loaded instance across calls for the same sandbox) would cut repeat call cost
significantly — but that is a follow-on optimisation, not required for v1.

Pyodide package bundle size

The pyodide npm package ships prebuilt wheels. Only the packages actually imported are
loaded from the package bundle. A minimal numpy + pandas + openpyxl bundle is ~30–40 MB
compressed. This increases the Docker image size and the ACA container cold-pull time.

---

6. Security posture — unchanged

The proposal keeps the security posture identical to current stdlib Python:

• User Python runs inside Pyodide's WASM sandbox — not as a host process (audit C1 preserved)
• The custom command wrapper is trusted sql-fs code, same as the existing nodeCommand
• ctx.fs.readFile() is scoped to the sandbox by SqlFs's RLS/tenant isolation — no cross-sandbox leakage
• network: false remains the default — Pyodide has no outbound network access unless the
  sandbox is created with network: true
• defenseInDepth wrapping (JUST_BASH_DEFENSE_IN_DEPTH) applies at the bash.exec layer,
  not inside the custom command. The Pyodide command runs trusted Node.js code and does not
  need DefenseInDepthBox.runTrustedAsync (unlike the Postgres I/O paths)

---

7. Open questions before implementation

1. File drain strategy: After a Pyodide script runs, which files need to be written back to
   SqlFs? Options: (a) diff the FS before/after, (b) intercept FS.writeFile / FS.open for
   writes and mirror them live, (c) drain all non-stdlib paths. Option (b) is cleanest but
   requires patching Pyodide's FS layer.

2. Lazy vs eager file loading: Loading all sandbox files into Pyodide FS upfront is simple
   but wastes memory for sandboxes with many files the script never reads. A lazy bridge
   (intercept FS.open and load on demand from SqlFs) would be more efficient but complex.
   For v1, eager loading of all files is acceptable.

3. -c inline code vs file argument: The current stdlib python3 supports both
   python3 script.py and python3 -c "code". The Pyodide command must handle both
   arg forms.

4. getAllPaths on CommandContext: ctx.fs is just-bash's IFileSystem. The current
   interface may not expose getAllPaths() (that's a SqlFs extension). The command may need to
   walk the FS recursively using ctx.fs.readdir() / ctx.fs.stat() instead.

5. Worker pool / session reuse: loadPyodide() is expensive. For a "write-once, run-once"
   pattern this is fine. If agents run many short Python scripts in one session, repeated
   loadPyodide() calls are a 2–3 s penalty per exec. A per-session cached Pyodide instance
   (stored in the Session object) would eliminate this — worth designing in from the start.

6. MAX_CONCURRENT_PYODIDE and the existing pythonSem: Pyodide execs must NOT consume
   slots from pythonSem (which guards stdlib Python workers). They need their own semaphore
   so a burst of Pyodide execs doesn't starve stdlib Python and vice versa.

---

8. Required updates — SDK, MCP, skills, OpenAPI

8.1 Python SDK (clients/python/)

src/sqlfs/models.py

• SandboxRecord: remove python: bool, add python_runtime: PythonRuntime | None
• PythonRuntime = Literal["stdlib", "pyodide"] type alias
• from_payload: read payload.get("python_runtime") instead of payload.get("python")

src/sqlfs/sandbox.py — Sandbox.create()

• Remove python: bool = False parameter
• Add python_runtime: PythonRuntime | None = None
• Body construction: if python_runtime: body["python_runtime"] = python_runtime

src/sqlfs/client.py (if it has a top-level create_sandbox wrapper)

• Same parameter rename

examples/quickstart.py

# before
sb = client.sandboxes.create(python=True)
# after
sb = client.sandboxes.create(python_runtime="stdlib")
# or for Pyodide:
sb = client.sandboxes.create(python_runtime="pyodide")

---

8.2 TypeScript SDK (clients/typescript/)

src/models.ts

• SandboxRecord: remove python: boolean, add python_runtime: PythonRuntime | null
• export type PythonRuntime = "stdlib" | "pyodide"
• fromPayload: read payload.python_runtime ?? null instead of Boolean(payload.python)

src/sandbox.ts (or src/client.ts) — CreateSandboxOptions

• Remove python?: boolean
• Add python_runtime?: PythonRuntime
• Body construction: send python_runtime instead of python

examples/quickstart.ts

// before
const sb = await client.sandboxes.create({ python: true });
// after
const sb = await client.sandboxes.create({ python_runtime: "stdlib" });

---

8.3 MCP tools (src/api/mcp/tools.ts)

sandbox_create tool — Zod input schema:

// before
python: z.boolean().optional(),

// after
python_runtime: z.enum(["stdlib", "pyodide"]).optional(),

Tool description string: replace "opt in to python3/python (CPython WASM, stdlib only)"
with "opt in to a Python runtime: stdlib (CPython WASM, stdlib only) or pyodide
(Pyodide WASM, numpy/pandas/openpyxl available)".

Runtime construction at line 44: python_runtime: args.python_runtime ?? null.

Response JSON at line 62: return python_runtime instead of python.

sandbox_list / sandbox info response (line 98): return python_runtime not python.

Exec tool description (lines 175–177): update the runtime hint block:

Optional runtimes (only if sandbox was created with a python_runtime or javascript:true):
- python3 / python — stdlib runtime: CPython WASM, stdlib only (no pip, no network).
- python3 / python — pyodide runtime: Pyodide WASM, numpy/pandas/openpyxl available.
  Each call cold-boots Pyodide (~5–8 s); write multi-step logic to a file and run once.
- js-exec / node — QuickJS WASM, Node.js-compatible stdlib.

---

8.4 OpenAPI spec (src/api/openapi-spec.ts)

SandboxObject schema (line 23):

// before
python: { type: "boolean", example: false },

// after
python_runtime: {
  type: "string",
  enum: ["stdlib", "pyodide"],
  nullable: true,
  example: null,
  description: "Active Python runtime, or null if Python is not enabled",
},

required array (line 26): replace "python" with "python_runtime".

Create sandbox request body (line 321):

// before
python: { type: "boolean", default: false, description: "Enable CPython WASM runtime" },

// after
python_runtime: {
  type: "string",
  enum: ["stdlib", "pyodide"],
  nullable: true,
  description: "Python runtime to enable. 'stdlib': CPython WASM stdlib-only. 'pyodide': Pyodide WASM with numpy/pandas/openpyxl.",
},

---

8.5 Skills / plugin docs (plugins/sql-fs/)

skills/api/ref/endpoints.md

• All create-sandbox request/response examples: replace "python": false with
  "python_runtime": null (or "stdlib" / "pyodide" where shown as enabled)
• The capabilities table row for python → new rows:

Field	Type	Default	Description
python_runtime	"stdlib" | "pyodide" | null	null	Python runtime. stdlib: CPython WASM, stdlib only. pyodide: Pyodide WASM, numpy/pandas/openpyxl.

• Remove the note: "python/javascript/network must be set at creation" → update to
  "python_runtime/javascript/network must be set at creation"

skills/api/ref/bash.md — "Python — python: true" section (line 48)

Rename section to "Python runtimes", split into two subsections:

### `python_runtime: "stdlib"` — CPython WASM
Stdlib only. ~1.5 s cold start per call. 8 MB single-file read limit (chunk larger files).
Server cap: 5 concurrent executions, ~80 MB RAM each.

### `python_runtime: "pyodide"` — Pyodide WASM
numpy, pandas, scipy, openpyxl available. ~5–8 s cold start per call. No file size limit.
Server cap: 2 concurrent executions, ~350–400 MB RAM each. Requires a larger ACA container
(4 GB recommended) if running alongside stdlib Python.

skills/py-sdk/ref/models.md

• SandboxRecord table: remove python: bool row, add python_runtime: str | None
• Example: sb.record.python_runtime instead of sb.record.python

skills/py-sdk/ref/sandbox.md

• create() signature: remove python: bool, add python_runtime: str | None = None
• All examples: create(python_runtime="stdlib") or create(python_runtime="pyodide")
• The capability probe note (line 92): update to reference python_runtime="stdlib"

---

9. What does NOT need to change

• just-bash: no fork required. Custom command API is sufficient.
• SqlFs / dialects: no changes. File access is via ctx.fs (same IFileSystem interface).
• HTTP routes (exec, ingest-files, files): no changes. The runtime difference is
  invisible at the HTTP layer — bash_exec looks identical from the SDK/MCP side.
• MCP tools: no changes.
• Python SDK / TS SDK: create_sandbox replaces the python: bool param with
  python_runtime: Literal["stdlib", "pyodide"] | None. All other methods unchanged.

---

9. Recommended implementation order

Steps 1–10 can be done without installing pyodide and ship as one PR (API plumbing + SDK
rename). Step 11 onward is the Pyodide implementation PR.

PR 1 — API plumbing + SDK rename (no pyodide dependency yet)

1. DB migration — replace python boolean with python_runtime varchar(16) NULL in
   all three dialect migration sets.
2. types.ts — add PythonRuntime type, replace python: boolean with
   pythonRuntime: PythonRuntime | null in SandboxMeta / SandboxListEntry.
3. session-manager.ts — replace python: boolean in RuntimeOptions with
   pythonRuntime: PythonRuntime | null, add pyodideSem, wire conditional command registration.
4. sandboxes.ts — replace python with python_runtime in create/get/list schema
   and response bodies.
5. openapi-spec.ts — update SandboxObject and create request body schemas.
6. mcp/tools.ts — update sandbox_create Zod schema, description strings, response JSON.
7. Python SDK (models.py, sandbox.py, examples) — rename field.
8. TypeScript SDK (models.ts, sandbox.ts/client.ts, examples) — rename field.
9. Skills / plugin docs (endpoints.md, bash.md, models.md, sandbox.md) — update
   all references per section 8.5 above.
10. CLAUDE.md — add MAX_CONCURRENT_PYODIDE, PYODIDE_QUEUE_TIMEOUT_MS,
    PYODIDE_EXEC_TIMEOUT_MS to env table.

PR 2 — Pyodide implementation

11. pnpm add pyodide — add npm dependency.
12. src/api/commands/pyodide-command.ts — implement custom command.
13. Tests — unit test with mock ctx.fs; integration test python_runtime: "pyodide".
14. Changeset — pnpm changeset with major bump (breaking: python removed from
    API and all SDKs).

[Hazzng]

NIce! make sure to do major change bump in changeset