Ajax Davis 846676ba15 refactor(executor): use Vercel Sandbox SDK for isolated VM execution

- Replace community Deno runtime with @vercel/sandbox SDK
- Next.js API routes create ephemeral sandbox VMs per execution
- Each tool execution: create VM → npm install → run → cleanup
- node22 runtime in sandbox handles npm packages natively
- Region pinned to iad1 (only region with Sandbox support)
- Proper authentication support via EXECUTOR_API_KEY

This provides true isolation - each tool runs in its own VM that's
destroyed after execution. More secure than shared serverless.

2026-01-09 01:35:22 +10:00

3.8 KiB

Raw Blame History

TPMJS Executor for Vercel

Deploy your own TPMJS tool executor using Vercel Sandbox for secure, isolated code execution.

Features

Secure Execution: Tools run in isolated Vercel Sandbox VMs
Full Control: Your infrastructure, your environment variables
Privacy: No data passes through TPMJS servers
One-Click Deploy: Deploy to Vercel in minutes

One-Click Deploy

How It Works

This executor uses Vercel Sandbox to:

Create an isolated VM for each tool execution
Install the npm package in the sandbox
Execute the tool with your parameters
Return the result and destroy the sandbox

This provides secure, isolated execution without the limitations of Node.js serverless functions.

API Endpoints

GET /api/health

Check executor health status.

curl https://your-executor.vercel.app/api/health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "info": {
    "runtime": "vercel-sandbox",
    "region": "iad1",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

POST /api/execute-tool

Execute a TPMJS tool.

curl -X POST https://your-executor.vercel.app/api/execute-tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "packageName": "@tpmjs/hello",
    "name": "helloWorld",
    "version": "latest",
    "params": { "name": "World" }
  }'

Response:

{
  "success": true,
  "output": "Hello, World!",
  "executionTimeMs": 2345
}

Configuration

Environment Variables

Variable	Required	Description
`EXECUTOR_API_KEY`	No	API key for authentication. If set, requests must include `Authorization: Bearer <key>` header.

Add custom environment variables for your tools (e.g., MY_API_KEY, DATABASE_URL) in your Vercel project settings.

Setting Up API Key Authentication

Go to your Vercel project settings
Add an environment variable: EXECUTOR_API_KEY with a secure random value
When configuring your executor in TPMJS, enter this key in the "API Key" field

Connecting to TPMJS

Go to your TPMJS collection or agent settings
In "Executor Configuration", select "Custom Executor"
Enter your executor URL: https://your-executor.vercel.app
Enter your API key (if configured)
Click "Verify Connection" to test

Local Development

# Install dependencies
npm install

# Login to Vercel (required for sandbox access)
vercel login

# Link to your Vercel project
vercel link

# Pull environment variables
vercel env pull

# Run development server
npm run dev

# Test the health endpoint
curl http://localhost:3000/api/health

Note: Vercel Sandbox requires authentication even in development. Run vercel login and vercel link first.

Security

Set EXECUTOR_API_KEY to require authentication for all requests
Tools run in isolated VMs with no access to your Vercel project
Each execution gets a fresh sandbox instance
Sandboxes are destroyed after execution completes

Pricing

Vercel Sandbox usage is billed based on compute time. See Vercel Sandbox Pricing for details.

Hobby: 45 min max runtime
Pro: 5 hour max runtime
Region: Currently only available in iad1

3.8 KiB Raw Blame History