tpmjs/services/sandbox-executor

TPMJS Sandbox Executor Service

Isolated microservice for securely executing TPMJS npm packages using isolated-vm.

Architecture

This service runs separately from the main Next.js application to provide:

• Secure sandboxing using V8 isolates
• Resource limits (128MB memory, 10s timeout)
• Package caching for faster subsequent executions
• Isolation from main app - no risk of compromising the web app

API Endpoints

POST /execute

Execute an npm package function.

Request:

{
  "packageName": "@tpmjs/createblogpost",
  "functionName": "default",
  "params": {
    "topic": "TypeScript best practices",
    "length": "medium"
  }
}

Response:

{
  "success": true,
  "output": "Generated blog post content...",
  "executionTimeMs": 1234,
  "logs": []
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "tpmjs-sandbox-executor",
  "version": "1.0.0",
  "memoryLimit": "128MB",
  "timeout": "10000ms"
}

POST /cache/clear

Clear the npm package cache.

Environment Variables

• PORT - Server port (default: 3000)
• PACKAGE_CACHE_DIR - Package cache directory (default: /tmp/.tpmjs-cache)
• ALLOWED_ORIGINS - Comma-separated list of allowed CORS origins (default: *)

Deployment

Railway

1. Initialize Railway project:

railway init

2. Link to existing project or create new:

railway link

3. Deploy:

railway up

4. Set environment variables:

railway variables set ALLOWED_ORIGINS=https://tpmjs.com,https://tpmjs-web.vercel.app

5. Get the service URL:

railway domain

Local Development

npm install
npm run dev

Test locally:

curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "@tpmjs/createblogpost",
    "params": {"topic": "TypeScript"}
  }'

Security

• Runs in isolated V8 context
• 128MB memory limit per execution
• 10 second timeout
• No filesystem access from sandbox
• No network access from sandbox
• Packages cached in /tmp

Integration with Next.js

Update the Next.js API route to call this service:

// apps/web/src/app/api/tools/execute/[...slug]/route.ts

const SANDBOX_URL = process.env.SANDBOX_EXECUTOR_URL;

const response = await fetch(`${SANDBOX_URL}/execute`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    packageName,
    functionName: 'default',
    params
  })
});

const result = await response.json();

Monitoring

Check logs:

railway logs

Monitor resource usage:

railway status