846676ba15
- 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.
143 lines
3.8 KiB
Markdown
143 lines
3.8 KiB
Markdown
# 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
|
|
|
|
[](https://vercel.com/new/clone?repository-url=https://github.com/tpmjs/tpmjs/tree/main/templates/vercel-executor&project-name=tpmjs-executor&repository-name=tpmjs-executor)
|
|
|
|
## How It Works
|
|
|
|
This executor uses [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) to:
|
|
|
|
1. Create an isolated VM for each tool execution
|
|
2. Install the npm package in the sandbox
|
|
3. Execute the tool with your parameters
|
|
4. 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.
|
|
|
|
```bash
|
|
curl https://your-executor.vercel.app/api/health
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```bash
|
|
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:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
1. Go to your Vercel project settings
|
|
2. Add an environment variable: `EXECUTOR_API_KEY` with a secure random value
|
|
3. When configuring your executor in TPMJS, enter this key in the "API Key" field
|
|
|
|
## Connecting to TPMJS
|
|
|
|
1. Go to your TPMJS collection or agent settings
|
|
2. In "Executor Configuration", select "Custom Executor"
|
|
3. Enter your executor URL: `https://your-executor.vercel.app`
|
|
4. Enter your API key (if configured)
|
|
5. Click "Verify Connection" to test
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
# 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](https://vercel.com/docs/vercel-sandbox/pricing) for details.
|
|
|
|
- **Hobby**: 45 min max runtime
|
|
- **Pro**: 5 hour max runtime
|
|
- **Region**: Currently only available in `iad1`
|
|
|
|
## Support
|
|
|
|
- [TPMJS Custom Executors Documentation](https://tpmjs.com/docs/executors)
|
|
- [TPMJS Custom Executor Tutorial](https://tpmjs.com/docs/tutorials/custom-executor)
|
|
- [Vercel Sandbox Documentation](https://vercel.com/docs/vercel-sandbox)
|
|
- [GitHub Issues](https://github.com/tpmjs/tpmjs/issues)
|