Custom Executors

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.

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

Deploy Your Own Executor

The fastest way to get started is to deploy our template to Vercel with one click:

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

Configuration

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

1. Go to your collection or agent settings
2. In the "Executor Configuration" section, select "Custom Executor"
3. Enter your executor URL (e.g., https://tpmjs-executor.vercel.app)
4. Optionally add an API key if your executor requires authentication
5. Click "Verify Connection" to test the configuration

Executor API Specification

All executors must implement this API:

// POST /execute-tool
{
  "packageName": "@tpmjs/hello",
  "name": "helloWorld",
  "version": "latest",
  "params": { "name": "World" },
  "env": { "MY_API_KEY": "..." }
}

// Response
{
  "success": true,
  "output": "Hello, World!",
  "executionTimeMs": 123
}

// GET /health
{
  "status": "ok",
  "version": "1.0.0"
}

Executor Cascade

Executor configuration follows a cascade resolution order:

• • If an agent has an executor configured, all tools in that agent use it
• • If the agent has no executor but a collection does, tools from that collection use the collection's executor
• • If neither has an executor configured, the TPMJS default executor is used

FAQ