From 346a3f6da011c9f7460858d5c359500fb03ea728 Mon Sep 17 00:00:00 2001 From: Ajax Davis Date: Fri, 9 Jan 2026 00:55:54 +1000 Subject: [PATCH] docs: add step-by-step custom executor tutorial - Create comprehensive tutorial at /docs/tutorials/custom-executor - Walk through from zero to running custom executor in 6 steps - Cover prerequisites, Vercel deployment, environment config - Include verification, testing, and connection to collections - Add troubleshooting section for common issues - Link tutorial from tutorials index and executors reference page --- apps/web/src/app/docs/executors/page.tsx | 21 + .../docs/tutorials/custom-executor/page.tsx | 545 ++++++++++++++++++ apps/web/src/app/docs/tutorials/page.tsx | 9 + 3 files changed, 575 insertions(+) create mode 100644 apps/web/src/app/docs/tutorials/custom-executor/page.tsx diff --git a/apps/web/src/app/docs/executors/page.tsx b/apps/web/src/app/docs/executors/page.tsx index ffe21eb..f383eb0 100644 --- a/apps/web/src/app/docs/executors/page.tsx +++ b/apps/web/src/app/docs/executors/page.tsx @@ -50,6 +50,27 @@ export default function ExecutorsDocsPage(): React.ReactElement {

+ {/* 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?

diff --git a/apps/web/src/app/docs/tutorials/custom-executor/page.tsx b/apps/web/src/app/docs/tutorials/custom-executor/page.tsx new file mode 100644 index 0000000..653264b --- /dev/null +++ b/apps/web/src/app/docs/tutorials/custom-executor/page.tsx @@ -0,0 +1,545 @@ +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 Your Own Executor - Tutorial - TPMJS', + description: + 'Step-by-step guide to deploy and configure your own custom executor for TPMJS tools in under 10 minutes.', +}; + +const envVarsExample = `# Optional: Require authentication for all requests +EXECUTOR_API_KEY=your-secret-api-key + +# Optional: Custom environment variables for your tools +MY_API_KEY=sk-xxx +DATABASE_URL=postgresql://...`; + +const verifyCommand = 'curl -X GET https://your-executor.vercel.app/health'; + +const verifyResponse = `{ + "status": "ok", + "version": "1.0.0" +}`; + +const testExecutionCommand = `curl -X POST https://your-executor.vercel.app/execute-tool \\ + -H "Content-Type: application/json" \\ + -H "Authorization: Bearer your-secret-api-key" \\ + -d '{ + "packageName": "@anthropic-ai/tpmjs-hello", + "name": "helloWorld", + "params": { "name": "World" } + }'`; + +const testExecutionResponse = `{ + "success": true, + "output": "Hello, World!", + "executionTimeMs": 145 +}`; + +export default function CustomExecutorTutorialPage(): React.ReactElement { + return ( +
+ + +
+
+ {/* Header */} +
+
+ + Docs + + + + Tutorials + + + Custom Executor +
+

+ Deploy Your Own Executor in 10 Minutes +

+

+ This tutorial walks you through deploying a custom executor to Vercel and connecting + it to your TPMJS collections. No coding required. +

+
+ + {/* Prerequisites */} +
+

Prerequisites

+
+
+
+ +
+
+

Vercel Account

+

+ Free tier works great.{' '} + + Sign up here + {' '} + if you don't have one. +

+
+
+
+
+ +
+
+

TPMJS Account

+

+ You'll need a collection or agent to connect your executor to.{' '} + + Create an account + {' '} + if needed. +

+
+
+
+
+ + {/* Step 1 */} +
+
+
+ 1 +
+

+ Deploy the Executor Template +

+
+ +

+ Click the button below to deploy the TPMJS executor template to your Vercel account. + This creates a private copy you fully control. +

+ + + +
+

What happens when you click:

+
    +
  1. Vercel clones the executor template to your GitHub account
    2. +
  2. A new Vercel project is created and linked to the repository
    3. +
  3. + The executor is automatically deployed to a URL like{' '} + + tpmjs-executor-xxx.vercel.app + +
    4. +
  4. Future pushes to your repo trigger automatic redeployments
    5. +
+
+
+ + {/* Step 2 */} +
+
+
+ 2 +
+

+ Configure Environment Variables (Optional) +

+
+ +

+ After deployment, you can add environment variables for security and customization. Go + to your Vercel project → Settings → Environment Variables. +

+ + + +
+
+ +
+

+ Security Recommendation +

+

+ Set EXECUTOR_API_KEY to + require authentication. Without it, anyone with your executor URL can execute + tools. +

+
+
+
+
+ + {/* Step 3 */} +
+
+
+ 3 +
+

+ Verify Your Executor is Running +

+
+ +

+ Once deployed, test that your executor is healthy by calling the health endpoint. + Replace the URL with your actual deployment URL. +

+ +
+
+

Run this command:

+ +
+ +
+

Expected response:

+ +
+
+ +
+
+ +

+ If you see{' '} + + "status": "ok" + + , your executor is running and ready to use! +

+
+
+
+ + {/* Step 4 */} +
+
+
+ 4 +
+

+ Test Tool Execution (Optional) +

+
+ +

+ Before connecting to TPMJS, you can verify tool execution works directly. This calls + the hello world tool on your executor. +

+ +
+
+

Test execution:

+ +
+ +
+

Expected response:

+ +
+
+
+ + {/* Step 5 */} +
+
+
+ 5 +
+

Connect to Your Collection

+
+ +

+ Now connect your executor to a TPMJS collection so all tools in that collection run on + your infrastructure. +

+ +
    +
  1. + + a + +
    +

    + Go to your{' '} + + Collections dashboard + +

    +
    +
    2. +
  2. + + b + +
    +

    + Click on the collection you want to use your executor with +

    +
    +
    3. +
  3. + + c + +
    +

    Click the "Edit" button

    +
    +
    4. +
  4. + + d + +
    +

    + In the "Executor Configuration" section, select "Custom + Executor" +

    +
    +
    5. +
  5. + + e + +
    +

    + Enter your executor URL (e.g.,{' '} + + https://tpmjs-executor-xxx.vercel.app + + ) +

    +
    +
    6. +
  6. + + f + +
    +

    + If you set an API key, enter it in the "API Key" field +

    +
    +
    7. +
  7. + + g + +
    +

    + Click "Verify Connection" to test the configuration +

    +
    +
    8. +
  8. + + h + +
    +

    Click "Save Changes"

    +
    +
    9. +
+ +
+
+ +
+

Pro Tip

+

+ You can also configure executors at the Agent level. Agent executor config takes + priority over collection config. See{' '} + + executor cascade + {' '} + for details. +

+
+
+
+
+ + {/* Step 6 */} +
+
+
+ 6 +
+

You're Done!

+
+ +

+ All tools in your collection now execute on your custom executor. When you or anyone + else uses your collection via MCP, the tools run on your Vercel deployment instead of + the TPMJS default executor. +

+ +
+
+
+ +

Full Privacy

+
+

+ Tool execution happens entirely on your infrastructure. No data passes through + TPMJS servers. +

+
+
+
+ +

Custom Environment

+
+

+ Add your own API keys and secrets as environment variables in Vercel. +

+
+
+
+ +

Your Limits

+
+

+ Execution timeouts and rate limits are controlled by your Vercel plan. +

+
+
+
+ +

Full Control

+
+

+ Fork and modify the executor code to add custom functionality. +

+
+
+
+ + {/* Troubleshooting */} +
+

Troubleshooting

+ +
+
+

+ "Verification failed" when connecting +

+
    +
  • Check that your executor URL is correct (no trailing slash)
    • +
  • + Ensure the executor is deployed and healthy (check{' '} + /health endpoint) +
    • +
  • + If using an API key, make sure it matches what's in Vercel environment + variables +
    • +
+
+ +
+

Tools timing out

+
    +
  • Vercel's free tier has a 10-second timeout per request
    • +
  • Upgrade to Pro for 60-second timeouts, or use a different host
    • +
  • Consider caching or optimizing slow tools
    • +
+
+ +
+

+ "Unauthorized" errors +

+
    +
  • + Your executor has{' '} + EXECUTOR_API_KEY set + but you didn't provide it in TPMJS +
    • +
  • Go to your collection/agent settings and add the API key
    • +
+
+
+
+ + {/* Next Steps */} +
+

Next Steps

+
+ + +
+

API Reference

+

+ Full executor API specification +

+
+ + + +
+

Your Collections

+

Manage executor settings

+
+ + + +
+

Executor Source

+

View and customize the code

+
+ + + +
+

MCP Setup

+

Connect to Claude Desktop

+
+ +
+
+
+
+ + +
+ ); +} diff --git a/apps/web/src/app/docs/tutorials/page.tsx b/apps/web/src/app/docs/tutorials/page.tsx index 61d7d11..a1e2565 100644 --- a/apps/web/src/app/docs/tutorials/page.tsx +++ b/apps/web/src/app/docs/tutorials/page.tsx @@ -31,6 +31,15 @@ const tutorials: Tutorial[] = [ duration: '4 min', steps: 8, }, + { + title: 'Deploy Your Own Executor', + description: + 'Run TPMJS tools on your own infrastructure. Deploy a custom executor to Vercel in minutes for full privacy, control, and custom environment variables.', + icon: '🚀', + href: '/docs/tutorials/custom-executor', + duration: '10 min', + steps: 6, + }, ]; export default function TutorialsPage(): React.ReactElement {