From 3f62228c568dfbe9185d9584729bef0c8a78790b Mon Sep 17 00:00:00 2001 From: Ajax Davis Date: Tue, 3 Feb 2026 21:47:13 +1000 Subject: [PATCH] docs(executors): add Unsandbox and Vercel deployment guides Restructure executor documentation to support multiple platforms: - Main /docs/executors page now serves as overview with platform selector - Add dedicated /docs/executors/unsandbox guide with CLI deployment - Add dedicated /docs/executors/vercel guide with one-click deploy - Include platform comparison table and shared API specification --- apps/web/src/app/docs/executors/page.tsx | 359 ++++++++++----- .../src/app/docs/executors/unsandbox/page.tsx | 420 +++++++++++++++++ .../src/app/docs/executors/vercel/page.tsx | 426 ++++++++++++++++++ 3 files changed, 1096 insertions(+), 109 deletions(-) create mode 100644 apps/web/src/app/docs/executors/unsandbox/page.tsx create mode 100644 apps/web/src/app/docs/executors/vercel/page.tsx diff --git a/apps/web/src/app/docs/executors/page.tsx b/apps/web/src/app/docs/executors/page.tsx index 4080f57..62b0197 100644 --- a/apps/web/src/app/docs/executors/page.tsx +++ b/apps/web/src/app/docs/executors/page.tsx @@ -1,4 +1,3 @@ -import { Button } from '@tpmjs/ui/Button/Button'; import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; import { Icon } from '@tpmjs/ui/Icon/Icon'; import type { Metadata } from 'next'; @@ -10,7 +9,7 @@ import { AppHeader } from '~/components/AppHeader'; export const metadata: Metadata = { title: 'Custom Executors - TPMJS', description: - 'Learn how to deploy and configure custom executors for running TPMJS tools on your own infrastructure.', + 'Deploy your own executor to run TPMJS tools on your own infrastructure with full control and privacy.', }; const executeToolExample = `// POST /execute-tool @@ -46,69 +45,39 @@ export default function ExecutorsDocsPage(): React.ReactElement {

Custom Executors

- Deploy your own executor to run TPMJS tools on your own infrastructure. + Deploy your own executor to run TPMJS tools on your infrastructure with full control + over environment, secrets, and data.

- {/* Quick Start Banner */} -
- -
-
🚀
-
-

- New to custom executors? Start with the tutorial -

-

- Deploy your own executor in 10 minutes with our step-by-step guide -

-
- -
- -
- - {/* Overview Section */} + {/* What is an Executor */}

What is an Executor?

An executor is a service that runs TPMJS tools. When you use a collection or agent, - TPMJS sends tool execution requests to an executor, which dynamically loads and runs - the tool code. + TPMJS sends tool execution requests to an executor, which dynamically loads the npm + package and calls the tool's{' '} + execute() function.

-

- By default, TPMJS uses a shared executor. You can deploy your own for: +

+ By default, TPMJS uses a shared executor. Deploying your own gives you complete + control over the execution environment.

+
+ + {/* Benefits Grid */} +
+

+ Why Deploy Your Own Executor? +

- -

Full Control

-
-

- Run tools on your own infrastructure with complete control over the execution - environment. -

-
-
-
- +

Privacy

- Keep tool execution data on your own servers. No data leaves your infrastructure. -

-
-
-
- -

Performance

-
-

- Deploy in regions closest to your users for lower latency tool execution. + Keep tool execution data on your own servers. No data passes through TPMJS.

@@ -117,68 +86,206 @@ export default function ExecutorsDocsPage(): React.ReactElement {

Custom Environment

- Inject your own environment variables, secrets, and configuration into tool - execution. + Inject your own API keys, database connections, and secrets into tool execution. +

+
+
+
+ +

Full Control

+
+

+ Choose your infrastructure, scale resources, and customize the execution + environment. +

+
+
+
+ +

No Timeouts

+
+

+ Run long-running tools without hitting shared executor time limits.

- {/* Deploy Section */} + {/* Choose Your Platform */}
-

- Deploy Your Own Executor -

+

Choose Your Platform

- The fastest way to get started is to deploy our template to Vercel with one click: + We provide deployment templates for multiple platforms. Choose the one that fits your + needs:

-
- + {/* Unsandbox Card */} + - - +
+
+ un +
+
+

+ Unsandbox +

+

+ Always-on container execution with automatic HTTPS. Deploy with one CLI + command. +

+
+ + Recommended + + + No cold starts + + + Unlimited runtime + +
+
+ +
+ + + {/* Vercel Card */} + +
+
+ + + +
+
+

+ Vercel +

+

+ Serverless execution with VM-level isolation using Vercel Sandbox. One-click + deploy. +

+
+ + One-click deploy + + + Free tier available + +
+
+ +
+
-

- After deployment, you'll get a URL like{' '} - - https://tpmjs-executor.vercel.app - + +

+ You can also build your own executor on any platform that runs Node.js. Just implement + the API specification below.

+ {/* Comparison Table */} +
+

Platform Comparison

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureUnsandboxVercel
Deploy methodCLI commandOne-click button
IsolationContainer-levelVM-level (Sandbox)
Cold starts + None (always-on) + Yes (serverless)
Max runtime + Unlimited + 45min (Hobby) / 5hr (Pro)
PricingPer uptimePer compute time
Custom domainsYesYes
Freeze/unfreezeYes (save costs)N/A (serverless)
+
+
+ {/* Configuration Section */}
-

Configuration

+

+ Connecting to Your Executor +

- Once you have your executor deployed, configure your collections or agents to use it: + Once deployed, configure your collections or agents to use your executor:

  1. Go to your collection or agent settings
    2. -
  2. - In the "Executor Configuration" section, select "Custom - Executor" -
    3. +
  3. In "Executor Configuration", select "Custom Executor"
  4. Enter your executor URL (e.g.,{' '} - https://tpmjs-executor.vercel.app + https://my-executor.on.unsandbox.com )
    5. -
  5. Optionally add an API key if your executor requires authentication
    6. -
  6. Click "Verify Connection" to test the configuration
    7. +
  7. Add your API key if authentication is enabled
    8. +
  8. Click "Verify Connection" to test

- Security tip: Set the{' '} - EXECUTOR_API_KEY environment - variable in your Vercel project to require authentication for all requests. + Security: Always set{' '} + EXECUTOR_API_KEY to require + authentication. Without it, anyone can execute tools on your executor.

@@ -188,7 +295,10 @@ export default function ExecutorsDocsPage(): React.ReactElement {

Executor API Specification

-

All executors must implement this API:

+

+ All executors must implement these endpoints. Use this spec if building a custom + executor. +

{/* POST /execute-tool */}
@@ -197,7 +307,9 @@ export default function ExecutorsDocsPage(): React.ReactElement { /execute-tool

- Execute a TPMJS tool with the provided parameters. + Execute a TPMJS tool. The executor should install the npm package, find the named + export, and call its{' '} + execute(params) function.

@@ -217,22 +329,33 @@ export default function ExecutorsDocsPage(): React.ReactElement { GET /health

- Check executor health status. Used by TPMJS to verify the executor is reachable. + Health check endpoint. TPMJS uses this to verify the executor is reachable and + working.

Response:

+ +
+

+ Note: Both{' '} + /api/health and{' '} + /health paths should work + (same for /execute-tool). + Our templates support both. +

+
- {/* Cascade Section */} + {/* Executor Cascade */}

Executor Cascade

- Executor configuration follows a cascade resolution order: + When a tool is executed, TPMJS resolves which executor to use in this order:

-
+
Agent Config @@ -255,35 +378,47 @@ export default function ExecutorsDocsPage(): React.ReactElement {
- {/* FAQ Section */} + {/* FAQ */}

FAQ

-

Can I use any cloud provider?

+

+ Which platform should I choose? +

- Yes! While we provide a Vercel template, you can deploy an executor anywhere that - can run Node.js and expose an HTTP endpoint. The executor just needs to implement - the API specification above. + Unsandbox is recommended for most use cases. It has no cold + starts, unlimited runtime, and simple CLI deployment. Use Vercel{' '} + if you're already on Vercel or prefer one-click deployment and pay-per-use + pricing.

-

What about timeouts?

+

Can I use other platforms?

- The default timeout for tool execution is 30 seconds. On Vercel's free tier, - you get up to 10 seconds per request. For longer-running tools, consider deploying - to a platform with higher timeout limits. + Yes! Any platform that runs Node.js and exposes HTTP endpoints works. AWS Lambda, + Google Cloud Run, Railway, Render, Fly.io—just implement the API specification + above.

How do tools get loaded?

- Tools are dynamically imported from{' '} - - esm.sh - - , a CDN for npm packages. The executor fetches the package, finds the tool export, - and calls its execute() function. + The executor runs npm install for + the requested package, then dynamically imports it and calls the tool's{' '} + execute() function. Each + execution uses a fresh temporary directory. +

+
+
+

+ Are environment variables secure? +

+

+ Yes. Environment variables are stored encrypted by the platform (Vercel/Unsandbox) + and only available during execution. You can also pass per-request environment + variables in the env field of the + execute-tool request.

@@ -302,16 +437,22 @@ export default function ExecutorsDocsPage(): React.ReactElement { target="_blank" rel="noopener noreferrer" > - + - +
diff --git a/apps/web/src/app/docs/executors/unsandbox/page.tsx b/apps/web/src/app/docs/executors/unsandbox/page.tsx new file mode 100644 index 0000000..715c2e5 --- /dev/null +++ b/apps/web/src/app/docs/executors/unsandbox/page.tsx @@ -0,0 +1,420 @@ +import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; +import { Icon } from '@tpmjs/ui/Icon/Icon'; +import type { Metadata } from 'next'; +import Link from 'next/link'; + +import { AppFooter } from '~/components/AppFooter'; +import { AppHeader } from '~/components/AppHeader'; + +export const metadata: Metadata = { + title: 'Deploy to Unsandbox - Custom Executors - TPMJS', + description: + 'Deploy a TPMJS executor to Unsandbox with one CLI command. Always-on, no cold starts, unlimited runtime.', +}; + +const deployCommand = `# Install the Unsandbox CLI +curl -fsSL https://unsandbox.com/install.sh | bash + +# Deploy the TPMJS executor +un service --name tpmjs-executor --ports 80 -n semitrusted \\ + --bootstrap "curl -fsSL https://raw.githubusercontent.com/tpmjs/tpmjs/main/templates/unsandbox-executor/bootstrap.sh | bash"`; + +const deployWithApiKey = `un service --name tpmjs-executor --ports 80 -n semitrusted \\ + -e EXECUTOR_API_KEY=your-secure-random-key \\ + --bootstrap "curl -fsSL https://raw.githubusercontent.com/tpmjs/tpmjs/main/templates/unsandbox-executor/bootstrap.sh | bash"`; + +const deployWithEnvVars = `un service --name tpmjs-executor --ports 80 -n semitrusted \\ + -e EXECUTOR_API_KEY=your-key \\ + -e OPENAI_API_KEY=sk-xxx \\ + -e DATABASE_URL=postgres://... \\ + --bootstrap "curl -fsSL https://raw.githubusercontent.com/tpmjs/tpmjs/main/templates/unsandbox-executor/bootstrap.sh | bash"`; + +const deployWithEnvFile = `# Create .env file with your secrets +cat > .env << EOF +EXECUTOR_API_KEY=your-key +OPENAI_API_KEY=sk-xxx +DATABASE_URL=postgres://... +EOF + +# Deploy with env file +un service --name tpmjs-executor --ports 80 -n semitrusted \\ + --env-file .env \\ + --bootstrap "curl -fsSL https://raw.githubusercontent.com/tpmjs/tpmjs/main/templates/unsandbox-executor/bootstrap.sh | bash"`; + +const healthCheck = `curl https://tpmjs-executor.on.unsandbox.com/api/health`; + +const healthResponse = `{ + "status": "ok", + "version": "1.0.0", + "info": { + "runtime": "unsandbox", + "timestamp": "2024-01-01T00:00:00.000Z" + } +}`; + +const executeExample = `curl -X POST https://tpmjs-executor.on.unsandbox.com/api/execute-tool \\ + -H "Content-Type: application/json" \\ + -H "Authorization: Bearer your-api-key" \\ + -d '{ + "packageName": "@tpmjs/hello", + "name": "helloWorldTool", + "version": "latest", + "params": { "includeTimestamp": true } + }'`; + +const localDev = `# Clone the repository +git clone https://github.com/tpmjs/tpmjs.git +cd tpmjs/templates/unsandbox-executor + +# Run locally +PORT=3000 node executor.js + +# Test health endpoint +curl http://localhost:3000/api/health`; + +const managementCommands = `# View logs +un service --logs tpmjs-executor + +# Redeploy (after updating) +un service --redeploy tpmjs-executor + +# Freeze when not in use (save costs) +un service --freeze tpmjs-executor + +# Unfreeze when needed +un service --unfreeze tpmjs-executor + +# Scale resources (4 vCPU, 8GB RAM) +un service --resize tpmjs-executor --vcpu 4 + +# Destroy service +un service --destroy tpmjs-executor`; + +const customDomain = `un service --name tpmjs-executor --ports 80 -n semitrusted \\ + --domains executor.yourdomain.com \\ + --bootstrap "curl -fsSL https://raw.githubusercontent.com/tpmjs/tpmjs/main/templates/unsandbox-executor/bootstrap.sh | bash"`; + +export default function UnsandboxExecutorPage(): React.ReactElement { + return ( +
+ + +
+
+ {/* Breadcrumb */} + + + {/* Header */} +
+
+
+ un +
+
+

Deploy to Unsandbox

+

+ Always-on execution with one CLI command +

+
+
+
+ + {/* Why Unsandbox */} +
+
+
+
0ms
+
No cold starts
+
+
+
∞
+
Unlimited runtime
+
+
+
1 cmd
+
Deploy in seconds
+
+
+
+ + {/* Quick Deploy */} +
+

Quick Deploy

+

+ Deploy a TPMJS executor with a single command. Your executor will be live at{' '} + + https://tpmjs-executor.on.unsandbox.com + +

+ +

+ This creates an always-on service that runs the executor. HTTPS is automatically + configured. +

+
+ + {/* Test Your Deployment */} +
+

Test Your Deployment

+

+ Verify your executor is running with a health check: +

+ +

Expected response:

+ +
+ + {/* Authentication */} +
+

Add Authentication

+
+

+ Important: Without an API key, anyone can execute tools on your + executor. Always set{' '} + EXECUTOR_API_KEY in production. +

+
+

+ Deploy with an API key to require authentication: +

+ +

+ When configured, requests must include{' '} + Authorization: Bearer your-api-key. +

+
+ + {/* Environment Variables */} +
+

Environment Variables

+

+ Pass environment variables that your tools need. These are available during tool + execution. +

+ +

Inline Variables

+ + +

Using an Env File

+ + +
+

+ All environment variables are stored encrypted and only available to your executor. +

+
+
+ + {/* Execute a Tool */} +
+

Execute a Tool

+

+ Test tool execution with a curl request: +

+ +
+ + {/* Local Development */} +
+

Local Development

+

+ Run the executor locally for testing and development: +

+ +
+ + {/* Management Commands */} +
+

Managing Your Service

+

+ Unsandbox provides commands to manage your executor: +

+ + +

Cost Optimization

+

+ Freeze your executor when not in use to stop billing: +

+
    +
  • + • un service --freeze stops the + service and billing +
    • +
  • + • un service --unfreeze restarts it + when needed +
    • +
  • • Configure auto-unfreeze to wake on HTTP request (incurs cold start)
    • +
+
+ + {/* Custom Domains */} +
+

Custom Domains

+

+ Use your own domain instead of the default{' '} + *.on.unsandbox.com: +

+ +

+ After deploying, add a CNAME record pointing{' '} + executor.yourdomain.com to your + Unsandbox service domain. +

+
+ + {/* How It Works */} +
+

How It Works

+

+ The Unsandbox executor runs as an always-on HTTP server: +

+
    +
  1. + + 1 + + + Receives tool execution request via HTTP POST to{' '} + /api/execute-tool + +
    2. +
  2. + + 2 + + Creates an isolated temporary directory for the execution +
    3. +
  3. + + 3 + + + Installs the npm package using{' '} + npm install + +
    4. +
  4. + + 4 + + + Loads the tool and calls its{' '} + execute() function + +
    5. +
  5. + + 5 + + Returns the result and cleans up the temporary directory +
    6. +
+

+ Since Unsandbox containers are already isolated, no additional sandbox layer is + needed. Network access is controlled by Unsandbox's semitrusted mode. +

+
+ + {/* Security */} +
+

Security

+
    +
  • + + + Set EXECUTOR_API_KEY to require + authentication + +
    • +
  • + + Tools run in isolated Unsandbox containers +
    • +
  • + + Each execution uses a fresh temporary directory +
    • +
  • + + Network controlled by semitrusted mode +
    • +
  • + + Environment variables stored encrypted +
    • +
+
+ + {/* Pricing */} +
+

Pricing

+

+ Unsandbox services are billed based on uptime. See{' '} + + Unsandbox Pricing + {' '} + for current rates. +

+
    +
  • + • HTTPS included via{' '} + *.on.unsandbox.com +
    • +
  • • Freeze when not in use to pause billing
    • +
  • • Scale vCPU and RAM as needed
    • +
+
+ + {/* Connect to TPMJS */} +
+

Connect to TPMJS

+
    +
  1. 1. Go to your collection or agent settings on TPMJS
    2. +
  2. 2. Select "Custom Executor" in Executor Configuration
    3. +
  3. + 3. Enter URL:{' '} + + https://tpmjs-executor.on.unsandbox.com + +
    4. +
  4. 4. Enter your API key (if configured)
    5. +
  5. 5. Click "Verify Connection"
    6. +
+
+ + {/* Navigation */} +
+ + + Back to Executors + + + Vercel Guide + + +
+
+
+ + +
+ ); +} diff --git a/apps/web/src/app/docs/executors/vercel/page.tsx b/apps/web/src/app/docs/executors/vercel/page.tsx new file mode 100644 index 0000000..0e23cb5 --- /dev/null +++ b/apps/web/src/app/docs/executors/vercel/page.tsx @@ -0,0 +1,426 @@ +import { Button } from '@tpmjs/ui/Button/Button'; +import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; +import { Icon } from '@tpmjs/ui/Icon/Icon'; +import type { Metadata } from 'next'; +import Link from 'next/link'; + +import { AppFooter } from '~/components/AppFooter'; +import { AppHeader } from '~/components/AppHeader'; + +export const metadata: Metadata = { + title: 'Deploy to Vercel - Custom Executors - TPMJS', + description: + 'Deploy a TPMJS executor to Vercel with one click. VM-level isolation using Vercel Sandbox.', +}; + +const healthCheck = `curl https://your-executor.vercel.app/api/health`; + +const healthResponse = `{ + "status": "ok", + "version": "1.0.0", + "info": { + "runtime": "vercel-sandbox", + "region": "iad1", + "timestamp": "2024-01-01T00:00:00.000Z" + } +}`; + +const executeExample = `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" } + }'`; + +const localDev = `# Clone and install +git clone https://github.com/tpmjs/tpmjs.git +cd tpmjs/templates/vercel-executor +npm install + +# Login to Vercel (required for sandbox) +vercel login +vercel link + +# Pull environment variables +vercel env pull + +# Run development server +npm run dev + +# Test health endpoint +curl http://localhost:3000/api/health`; + +export default function VercelExecutorPage(): React.ReactElement { + return ( +
+ + +
+
+ {/* Breadcrumb */} + + + {/* Header */} +
+
+
+ + + +
+
+

Deploy to Vercel

+

+ One-click deploy with VM-level isolation +

+
+
+
+ + {/* Why Vercel */} +
+
+
+
1-click
+
Deploy instantly
+
+
+
VM
+
Sandbox isolation
+
+
+
Free
+
Hobby tier available
+
+
+
+ + {/* One-Click Deploy */} +
+

One-Click Deploy

+

+ Deploy the TPMJS executor template to your Vercel account: +

+ + + +

+ After deployment, your executor will be available at{' '} + + https://tpmjs-executor.vercel.app + +

+
+ + {/* Test Your Deployment */} +
+

Test Your Deployment

+

Verify your executor is running:

+ +

Expected response:

+ +
+ + {/* Authentication */} +
+

Add Authentication

+
+

+ Important: Without an API key, anyone can execute tools on your + executor. Always set{' '} + EXECUTOR_API_KEY in production. +

+
+
    +
  1. + + 1 + + Go to your Vercel project settings +
    2. +
  2. + + 2 + + Navigate to Environment Variables +
    3. +
  3. + + 3 + + + Add EXECUTOR_API_KEY with a + secure random value + +
    4. +
  4. + + 4 + + Redeploy your project to apply the changes +
    5. +
+
+ + {/* Environment Variables */} +
+

Environment Variables

+

+ Add custom environment variables for your tools in Vercel project settings: +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
VariableRequiredDescription
+ EXECUTOR_API_KEY + No* + API key for authentication. Required for production. +
+ OPENAI_API_KEY + NoExample: Pass through to tools that need OpenAI
+ DATABASE_URL + NoExample: Pass through to tools that need database
+
+

+ * Strongly recommended for production deployments +

+
+ + {/* Execute a Tool */} +
+

Execute a Tool

+

+ Test tool execution with a curl request: +

+ +
+ + {/* Local Development */} +
+

Local Development

+

+ Run the executor locally for testing. Note: Vercel Sandbox requires authentication + even in development. +

+ +
+

+ Note: You must run{' '} + vercel login and{' '} + vercel link before local + development. Vercel Sandbox requires authentication to create VMs. +

+
+
+ + {/* How It Works */} +
+

How It Works

+

+ The Vercel executor uses{' '} + + Vercel Sandbox + {' '} + for isolated execution: +

+
    +
  1. + + 1 + + Creates an isolated VM for each tool execution +
    2. +
  2. + + 2 + + Installs the npm package in the sandbox +
    3. +
  3. + + 3 + + Executes the tool with your parameters +
    4. +
  4. + + 4 + + Returns the result and destroys the sandbox +
    5. +
+

+ This provides VM-level isolation without the limitations of Node.js serverless + functions. +

+
+ + {/* Security */} +
+

Security

+
    +
  • + + + Set EXECUTOR_API_KEY to require + authentication + +
    • +
  • + + 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 & Limits */} +
+

Pricing & Limits

+

+ Vercel Sandbox usage is billed based on compute time. See{' '} + + Vercel Sandbox Pricing + {' '} + for current rates. +

+
+ + + + + + + + + + + + + + + + + + + + +
PlanMax RuntimeNotes
Hobby45 minutesFree tier
Pro5 hoursFor longer-running tools
+
+
+

+ Region: Vercel Sandbox is currently only available in{' '} + iad1 (US East). +

+
+
+ + {/* Connect to TPMJS */} +
+

Connect to TPMJS

+
    +
  1. 1. Go to your collection or agent settings on TPMJS
    2. +
  2. 2. Select "Custom Executor" in Executor Configuration
    3. +
  3. + 3. Enter URL:{' '} + + https://tpmjs-executor.vercel.app + +
    4. +
  4. 4. Enter your API key (if configured)
    5. +
  5. 5. Click "Verify Connection"
    6. +
+
+ + {/* Navigation */} +
+ + + Unsandbox Guide + + + Back to Executors + + +
+
+
+ + +
+ ); +}