@parel/sandbox-vercel 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @parel/sandbox-vercel
+
+> PAREL sandbox capability provider plugin for Vercel Sandbox.
+
+A first-party runtime plugin for [PAREL](https://github.com/parall-hq/parel-opensource).
+
+## Install
+
+```bash
+npm install @parel/sandbox-vercel
+```
+
+## Usage
+
+Provides the standard `parel.sandbox` capability from `@parel/capability-sandbox`
+using the official `@vercel/sandbox` SDK. It supports filesystem operations,
+argv command execution, detached processes, port domains, and lifecycle
+management.
+
+```yaml
+plugins:
+  - plugin: sandbox-vercel
+    config:
+      token: <vercel token>
+      teamId: <team id>
+      projectId: <project id>
+      name: parel-agent
+      runtime: node24
+      ports: [3000]
+```
+
+Named sandboxes are reused through `Sandbox.getOrCreate`. By default the plugin
+deletes the sandbox on `session:end`; set `destroyOnSessionEnd: false` to stop it
+instead.
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { ParelPlugin } from '@parel/plugin-sdk';
+
+declare const _default: ParelPlugin;
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,323 @@
+// src/index.ts
+import { Buffer } from "buffer";
+import {
+  PAREL_SANDBOX_CAPABILITY
+} from "@parel/capability-sandbox";
+import { definePlugin, LifecycleEvent } from "@parel/plugin-sdk";
+import { Sandbox as VercelSandboxClient } from "@vercel/sandbox";
+
+// parel.plugin.json
+var parel_plugin_default = {
+  name: "@parel/sandbox-vercel",
+  version: "0.0.0",
+  description: "Provides the standard parel.sandbox capability backed by Vercel Sandbox.",
+  provides: {
+    capabilities: ["parel.sandbox"]
+  },
+  requires: {
+    permissions: {
+      network: true,
+      store: true
+    },
+    secrets: {
+      token: {
+        description: "Vercel API token or OIDC token",
+        required: true
+      },
+      teamId: {
+        description: "Vercel team id",
+        required: true
+      },
+      projectId: {
+        description: "Vercel project id for Sandbox operations",
+        required: true
+      }
+    }
+  },
+  config: {
+    name: "Optional named sandbox. Named sandboxes are reused with getOrCreate by default.",
+    runtime: "Optional Vercel Sandbox runtime, such as node24 or python3.13.",
+    ports: "Optional array of exposed ports.",
+    timeoutMs: "Optional sandbox timeout in milliseconds.",
+    destroyOnSessionEnd: "Defaults to true. When false, the sandbox is stopped instead of deleted."
+  },
+  execution: {
+    snapshot: {
+      store: "reset",
+      sandbox: "reset",
+      sideEffects: "require_approval"
+    }
+  }
+};
+
+// src/index.ts
+var STORE_KEY = "vercel_sandbox_name";
+function stringConfig(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function numberConfig(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") record[key] = entry;
+  }
+  return Object.keys(record).length > 0 ? record : void 0;
+}
+function numberArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "number") : void 0;
+}
+function limitOutput(value, maxOutputChars) {
+  if (!maxOutputChars || value.length <= maxOutputChars) return value;
+  return value.slice(0, maxOutputChars);
+}
+function mapStatsType(stats) {
+  if (stats.isDirectory?.()) return "directory";
+  if (stats.isSymbolicLink?.()) return "symlink";
+  if (stats.isFile?.()) return "file";
+  return "unknown";
+}
+function mapDirentType(dirent) {
+  if (dirent.isDirectory?.()) return "directory";
+  if (dirent.isSymbolicLink?.()) return "symlink";
+  if (dirent.isFile?.()) return "file";
+  return "unknown";
+}
+function mapCommandStatus(command) {
+  if (command.exitCode === null) return "running";
+  return command.exitCode === 0 ? "exited" : "failed";
+}
+async function commandResult(command, opts) {
+  return {
+    stdout: limitOutput(await command.stdout(), opts?.maxOutputChars),
+    stderr: limitOutput(await command.stderr(), opts?.maxOutputChars),
+    exitCode: command.exitCode,
+    metadata: { provider: "vercel", commandId: command.cmdId }
+  };
+}
+function runParams(command, opts) {
+  return {
+    cmd: command[0],
+    args: [...command.slice(1)],
+    cwd: opts?.cwd,
+    env: opts?.env,
+    timeoutMs: opts?.timeoutMs
+  };
+}
+function buildCreateParams(config) {
+  const params = {};
+  for (const key of ["name", "runtime"]) {
+    const value = stringConfig(config[key]);
+    if (value) params[key] = value;
+  }
+  const timeout = numberConfig(config.timeoutMs);
+  if (timeout !== void 0) params.timeout = timeout;
+  const ports = numberArray(config.ports);
+  if (ports) params.ports = ports;
+  const env = stringRecord(config.env);
+  if (env) params.env = env;
+  const tags = stringRecord(config.tags);
+  if (tags) params.tags = tags;
+  return params;
+}
+var index_default = definePlugin({
+  name: "@parel/sandbox-vercel",
+  provides: parel_plugin_default.provides,
+  requires: parel_plugin_default.requires,
+  execution: parel_plugin_default.execution,
+  async setup(ctx) {
+    const token = stringConfig(ctx.config.token);
+    const teamId = stringConfig(ctx.config.teamId);
+    const projectId = stringConfig(ctx.config.projectId);
+    const destroyOnSessionEnd = ctx.config.destroyOnSessionEnd !== false;
+    let sandbox = null;
+    function credentials() {
+      if (!token || !teamId || !projectId) {
+        ctx.log.warn("Vercel Sandbox token, teamId, and projectId are required");
+        return null;
+      }
+      return { token, teamId, projectId };
+    }
+    function requireSandbox() {
+      if (!sandbox) throw new Error("Vercel sandbox not available");
+      return sandbox;
+    }
+    async function ensureSandbox() {
+      const creds = credentials();
+      if (!creds) return null;
+      const savedName = await ctx.store.get(STORE_KEY);
+      const name = stringConfig(ctx.config.name) ?? savedName;
+      const params = { ...buildCreateParams(ctx.config), ...creds };
+      if (name) {
+        sandbox = await VercelSandboxClient.getOrCreate({
+          ...params,
+          name
+        });
+      } else {
+        sandbox = await VercelSandboxClient.create(params);
+      }
+      await ctx.store.set(STORE_KEY, sandbox.name);
+      ctx.log.info(`Vercel sandbox ready: ${sandbox.name}`);
+      return sandbox;
+    }
+    async function disposeSandbox() {
+      if (!sandbox) return;
+      try {
+        if (destroyOnSessionEnd) {
+          await sandbox.delete();
+          await ctx.store.delete(STORE_KEY);
+        } else {
+          await sandbox.stop();
+        }
+      } finally {
+        sandbox = null;
+      }
+    }
+    async function execCommand(command, opts) {
+      const finished = await requireSandbox().runCommand(
+        runParams(command, opts)
+      );
+      return commandResult(finished, opts);
+    }
+    async function shellCommand(command, opts) {
+      const shell = opts?.shell ?? "sh";
+      const finished = await requireSandbox().runCommand({
+        cmd: shell,
+        args: ["-lc", command],
+        cwd: opts?.cwd,
+        env: opts?.env,
+        timeoutMs: opts?.timeoutMs
+      });
+      return commandResult(finished, opts);
+    }
+    function processHandle(command, original) {
+      return {
+        id: command.cmdId,
+        command: original,
+        async status() {
+          return mapCommandStatus(command);
+        },
+        async wait(opts) {
+          const finished = await command.wait(opts ? { signal: void 0 } : void 0);
+          return commandResult(finished, opts);
+        },
+        async kill(signal) {
+          await command.kill(signal);
+        },
+        async stdout(opts) {
+          return limitOutput(await command.stdout(), opts?.maxChars);
+        },
+        async stderr(opts) {
+          return limitOutput(await command.stderr(), opts?.maxChars);
+        }
+      };
+    }
+    const capability = {
+      get id() {
+        return sandbox?.name;
+      },
+      provider: "vercel",
+      supports: {
+        fs: true,
+        process: true,
+        shell: true,
+        spawn: true,
+        ports: true,
+        lifecycle: true,
+        network: "enabled"
+      },
+      fs: {
+        async readFile(path, opts) {
+          const content = await requireSandbox().fs.readFile(path, {
+            encoding: opts?.encoding === "base64" ? null : "utf8"
+          });
+          const text = Buffer.isBuffer(content) ? content.toString("base64") : content;
+          return opts?.maxChars ? limitOutput(text, opts.maxChars) : text;
+        },
+        async writeFile(path, content, opts) {
+          const data = opts?.encoding === "base64" ? Buffer.from(content, "base64") : content;
+          if (opts?.append && requireSandbox().fs.appendFile) {
+            await requireSandbox().fs.appendFile?.(path, data);
+          } else {
+            await requireSandbox().fs.writeFile(path, data);
+          }
+        },
+        async listDir(path) {
+          return (await requireSandbox().fs.readdir(path, { withFileTypes: true })).map(
+            (entry) => ({
+              name: entry.name,
+              type: mapDirentType(entry)
+            })
+          );
+        },
+        async stat(path) {
+          const stats = await requireSandbox().fs.stat(path);
+          return {
+            path,
+            type: mapStatsType(stats),
+            size: stats.size,
+            mtimeMs: stats.mtimeMs,
+            mode: stats.mode
+          };
+        },
+        async exists(path) {
+          return requireSandbox().fs.exists(path);
+        },
+        async mkdir(path, opts) {
+          await requireSandbox().fs.mkdir(path, { recursive: opts?.recursive });
+        },
+        async remove(path, opts) {
+          await requireSandbox().fs.rm(path, { recursive: opts?.recursive, force: true });
+        },
+        async rename(from, to) {
+          await requireSandbox().fs.rename(from, to);
+        }
+      },
+      process: {
+        exec: execCommand,
+        shell: shellCommand,
+        async spawn(command, opts) {
+          const handle = await requireSandbox().runCommand({
+            ...runParams(command, opts),
+            detached: true
+          });
+          return processHandle(handle, command);
+        }
+      },
+      ports: {
+        async expose(port) {
+          return { port, url: requireSandbox().domain(port), protocol: "https" };
+        }
+      },
+      lifecycle: {
+        async isRunning() {
+          return String(sandbox?.status ?? "running") === "running";
+        },
+        async stop() {
+          await requireSandbox().stop();
+        },
+        async extendTimeout(timeoutMs) {
+          await requireSandbox().extendTimeout?.(timeoutMs);
+        }
+      }
+    };
+    ctx.hook(LifecycleEvent.SessionStart, async () => {
+      await ensureSandbox();
+    });
+    ctx.hook(LifecycleEvent.SessionResume, async () => {
+      await ensureSandbox();
+    });
+    ctx.hook(LifecycleEvent.SessionSuspend, async () => {
+      if (sandbox) await ctx.store.set(STORE_KEY, sandbox.name);
+    });
+    ctx.hook(LifecycleEvent.SessionEnd, async () => {
+      await disposeSandbox();
+    });
+    ctx.provide(PAREL_SANDBOX_CAPABILITY, capability);
+  }
+});
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@parel/sandbox-vercel",
+  "version": "0.1.1",
+  "description": "PAREL sandbox capability provider plugin for Vercel Sandbox.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parall-hq/parel-opensource.git",
+    "directory": "js/plugins/sandbox-vercel"
+  },
+  "bugs": {
+    "url": "https://github.com/parall-hq/parel-opensource/issues"
+  },
+  "homepage": "https://github.com/parall-hq/parel-opensource#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "parel.plugin.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "lint": "biome check src/"
+  },
+  "dependencies": {
+    "@parel/capability-sandbox": "workspace:*",
+    "@parel/plugin-sdk": "workspace:*",
+    "@vercel/sandbox": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "access": "public"
+  }
+}

package/parel.plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "@parel/sandbox-vercel",
+  "version": "0.0.0",
+  "description": "Provides the standard parel.sandbox capability backed by Vercel Sandbox.",
+  "provides": {
+    "capabilities": ["parel.sandbox"]
+  },
+  "requires": {
+    "permissions": {
+      "network": true,
+      "store": true
+    },
+    "secrets": {
+      "token": {
+        "description": "Vercel API token or OIDC token",
+        "required": true
+      },
+      "teamId": {
+        "description": "Vercel team id",
+        "required": true
+      },
+      "projectId": {
+        "description": "Vercel project id for Sandbox operations",
+        "required": true
+      }
+    }
+  },
+  "config": {
+    "name": "Optional named sandbox. Named sandboxes are reused with getOrCreate by default.",
+    "runtime": "Optional Vercel Sandbox runtime, such as node24 or python3.13.",
+    "ports": "Optional array of exposed ports.",
+    "timeoutMs": "Optional sandbox timeout in milliseconds.",
+    "destroyOnSessionEnd": "Defaults to true. When false, the sandbox is stopped instead of deleted."
+  },
+  "execution": {
+    "snapshot": {
+      "store": "reset",
+      "sandbox": "reset",
+      "sideEffects": "require_approval"
+    }
+  }
+}