feat: add S3 and SQLite virtual file system driver examples

- examples/virtual-file-system-s3: S3-backed VirtualFileSystem using @aws-sdk/client-s3, with Docker Compose for MinIO
- examples/virtual-file-system-sqlite: SQLite-backed VirtualFileSystem using sql.js (WASM), no native deps
- Both tested end-to-end: sandbox writes/reads files, host verifies via storage API
- docs/features/virtual-filesystem.mdx: linked examples with use case descriptions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

docs/features/virtual-filesystem.mdx

@@ -167,10 +167,30 @@ const result = await runtime.exec(`
   console.log(config.greeting);
 `);
 
-console.log(result.stdout); // "hello\n"
+// Output captured via onStdio callback — see Output Capture docs
 runtime.dispose();
 ```
 
+## More examples
+
+Full, tested implementations for common storage backends:
+
+<CardGroup cols={2}>
+  <Card title="S3 / MinIO" icon="cloud" href="https://github.com/rivet-dev/secure-exec/tree/main/examples/virtual-file-system-s3">
+    Store sandbox files as S3 objects. Works with any S3-compatible store (AWS, MinIO, R2). Includes Docker Compose for local testing with MinIO.
+  </Card>
+  <Card title="SQLite" icon="database" href="https://github.com/rivet-dev/secure-exec/tree/main/examples/virtual-file-system-sqlite">
+    Store sandbox files as rows in a SQLite database (via sql.js / WASM). Snapshot and restore entire filesystems. No external services needed.
+  </Card>
+</CardGroup>
+
+Other use cases you can build with `VirtualFileSystem`:
+
+- **Git-backed storage** — store files in a bare Git repo, with each sandbox session as a commit
+- **Encrypted filesystem** — wrap another VFS and encrypt/decrypt content transparently
+- **Union / overlay filesystem** — layer a writable VFS on top of a read-only base (e.g. template files + user modifications)
+- **Remote filesystem** — proxy file operations to a remote server via HTTP or gRPC
+
 ## Tips
 
 - **Throw Node-style errors.** Sandboxed code expects errors like `ENOENT`, `EACCES`, and `EISDIR`. Match the error message prefix so `fs` error handling works naturally.

examples/virtual-file-system-s3/README.md

@@ -0,0 +1,48 @@
+# S3 Filesystem Driver Example
+
+A custom filesystem driver backed by S3 (or any S3-compatible store like [MinIO](https://min.io)). Sandboxed code uses `fs.readFileSync`, `fs.writeFileSync`, and other Node.js filesystem APIs as normal — all I/O is transparently routed to S3 objects.
+
+[Docs](https://secureexec.dev/docs) | [GitHub](https://github.com/rivet-dev/secure-exec)
+
+## Start the test server
+
+Run MinIO locally with Docker:
+
+```bash
+docker compose up -d
+```
+
+Or without Docker Compose:
+
+```bash
+docker run -d -p 9000:9000 -p 9001:9001 \
+  -e MINIO_ROOT_USER=minioadmin \
+  -e MINIO_ROOT_PASSWORD=minioadmin \
+  minio/minio server /data --console-address ":9001"
+```
+
+MinIO console is available at http://localhost:9001 (login: minioadmin / minioadmin).
+
+## Run the example
+
+```bash
+pnpm install
+pnpm test
+```
+
+This creates a `NodeRuntime` with the S3-backed filesystem, runs sandboxed code that writes and reads files, then verifies the data was persisted to MinIO via the S3 API.
+
+## How it works
+
+- `S3FileSystem` implements the `VirtualFileSystem` interface from `secure-exec`
+- Files are stored as S3 objects keyed by their path (leading `/` stripped)
+- Directories are inferred from key prefixes; `mkdir` creates empty marker objects
+- `readDir` uses `ListObjectsV2` with delimiter-based prefix listing
+- Symlinks and hard links throw `ENOSYS` (not practical for object storage)
+- `chmod`, `chown`, `utimes` are no-ops (S3 doesn't have POSIX permissions)
+
+## Use cases
+
+- **Persistent sandboxes**: User-generated code writes files that survive across sessions
+- **Multi-tenant isolation**: Each sandbox gets its own S3 prefix or bucket
+- **Cloud-native deployments**: Store sandbox artifacts in the same object store as your application

examples/virtual-file-system-s3/docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  minio:
+    image: minio/minio
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    command: server /data --console-address ":9001"

examples/virtual-file-system-s3/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@secure-exec/example-virtual-file-system-s3",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "secure-exec": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

examples/virtual-file-system-s3/src/index.ts

@@ -0,0 +1,120 @@
+import {
+	NodeRuntime,
+	allowAllFs,
+	createNodeDriver,
+	createNodeRuntimeDriverFactory,
+} from "secure-exec";
+import {
+	S3Client,
+	CreateBucketCommand,
+	DeleteBucketCommand,
+	ListObjectsV2Command,
+	DeleteObjectCommand,
+} from "@aws-sdk/client-s3";
+import { S3FileSystem } from "./s3-filesystem.js";
+
+const BUCKET = "secure-exec-vfs-test";
+
+// Connect to MinIO (S3-compatible) running on localhost
+const client = new S3Client({
+	endpoint: "http://localhost:9000",
+	region: "us-east-1",
+	credentials: {
+		accessKeyId: "minioadmin",
+		secretAccessKey: "minioadmin",
+	},
+	forcePathStyle: true,
+});
+
+// Create test bucket
+try {
+	await client.send(new CreateBucketCommand({ Bucket: BUCKET }));
+} catch (err: unknown) {
+	const e = err as { name?: string };
+	if (
+		e.name !== "BucketAlreadyOwnedByYou" &&
+		e.name !== "BucketAlreadyExists"
+	) {
+		throw err;
+	}
+}
+
+const filesystem = new S3FileSystem({ client, bucket: BUCKET });
+
+const runtime = new NodeRuntime({
+	systemDriver: createNodeDriver({
+		filesystem,
+		permissions: { ...allowAllFs },
+	}),
+	runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+});
+
+try {
+	// Sandbox writes files — stored in MinIO via S3 API
+	const writeResult = await runtime.exec(`
+		const fs = require("node:fs");
+		fs.mkdirSync("/workspace", { recursive: true });
+		fs.writeFileSync("/workspace/hello.txt", "hello from sandbox via S3");
+		fs.writeFileSync("/workspace/data.json", JSON.stringify({ count: 42 }));
+		console.log("files written");
+	`);
+
+	if (writeResult.code !== 0) {
+		throw new Error(`Write step failed: ${writeResult.errorMessage}`);
+	}
+
+	// Sandbox reads files back
+	let readOutput = "";
+	const readResult = await runtime.exec(
+		`
+		const fs = require("node:fs");
+		const text = fs.readFileSync("/workspace/hello.txt", "utf8");
+		const data = JSON.parse(fs.readFileSync("/workspace/data.json", "utf8"));
+		const entries = fs.readdirSync("/workspace");
+		console.log(JSON.stringify({ text, count: data.count, entries }));
+	`,
+		{
+			onStdio: (event) => {
+				if (event.channel === "stdout") readOutput += event.message;
+			},
+		},
+	);
+
+	if (readResult.code !== 0) {
+		throw new Error(`Read step failed: ${readResult.errorMessage}`);
+	}
+
+	// Verify from host side via S3 API
+	const hostContent = await filesystem.readTextFile("/workspace/hello.txt");
+	const parsed = JSON.parse(readOutput.trim());
+
+	const ok =
+		hostContent === "hello from sandbox via S3" &&
+		parsed.text === "hello from sandbox via S3" &&
+		parsed.count === 42 &&
+		parsed.entries.includes("hello.txt") &&
+		parsed.entries.includes("data.json");
+
+	console.log(
+		JSON.stringify({
+			ok,
+			hostContent,
+			sandboxResult: parsed,
+			summary:
+				"S3-backed VFS: sandbox wrote files to MinIO, read them back, host verified via S3 API",
+		}),
+	);
+} finally {
+	runtime.dispose();
+
+	// Clean up: delete all objects and the bucket
+	const list = await client.send(
+		new ListObjectsV2Command({ Bucket: BUCKET }),
+	);
+	for (const obj of list.Contents ?? []) {
+		await client.send(
+			new DeleteObjectCommand({ Bucket: BUCKET, Key: obj.Key! }),
+		);
+	}
+	await client.send(new DeleteBucketCommand({ Bucket: BUCKET }));
+}