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 the npm package and calls the tool's execute() function.

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

Why Deploy Your Own Executor?

Choose Your Platform

We provide deployment templates for multiple platforms. Choose the one that fits your needs:

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

Platform Comparison

Connecting to Your Executor

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

1. Go to your collection or agent settings
2. In "Executor Configuration", select "Custom Executor"
3. Enter your executor URL (e.g., https://my-executor.on.unsandbox.com)
4. Add your API key if authentication is enabled
5. Click "Verify Connection" to test

Executor API Specification

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

// 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

When a tool is executed, TPMJS resolves which executor to use in this 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