Deploy to Unsandbox

Always-on execution with one CLI command

0ms

No cold starts

∞

Unlimited runtime

1 cmd

Deploy in seconds

Quick Deploy

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

# 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"

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

Test Your Deployment

Verify your executor is running with a health check:

curl https://tpmjs-executor.on.unsandbox.com/api/health

Expected response:

{
  "status": "ok",
  "version": "1.0.0",
  "info": {
    "runtime": "unsandbox",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

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:

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"

When configured, requests must include Authorization: Bearer your-api-key.

Environment Variables

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

Inline Variables

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"

Using an Env File

# 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"

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

Execute a Tool

Test tool execution with a curl request:

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 }
  }'

Local Development

Run the executor locally for testing and development:

# 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

Managing Your Service

Unsandbox provides commands to manage your executor:

# 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

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

Use your own domain instead of the default *.on.unsandbox.com:

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"

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

How It Works

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

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

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

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

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

1. Go to your collection or agent settings on TPMJS
2. Select "Custom Executor" in Executor Configuration
3. Enter URL: https://tpmjs-executor.on.unsandbox.com
4. Enter your API key (if configured)
5. Click "Verify Connection"

Railway Guide Vercel Guide