Cross-Environment Execution

TrikHub supports running triks written in different languages from any agent runtime. A Python agent can execute JavaScript triks, and vice versa.

The Problem

Without cross-environment support:

• Python developers can only use Python triks
• JavaScript developers can only use JavaScript triks
• The trik ecosystem is fragmented by language

With TrikHub’s worker system, language becomes an implementation detail. Use the best triks regardless of what language they’re written in.

How It Works

When you load a trik, the gateway checks its runtime from the manifest. If the trik is written in a different language than your agent, the gateway spawns a worker subprocess to execute it:

┌─────────────────┐     JSON-RPC 2.0    ┌─────────────────┐
│  Python Agent   │ ◄────────────────►  │  Node.js Worker │
│  (TrikGateway)  │      stdin/stdout   │ (@trikhub/      │
│                 │                     │   worker-js)    │
└────────┬────────┘                     └────────┬────────┘
         │                                       │
    Python Triks                            JS Triks
    (in-process)                          (in-process)

The same applies in reverse for JavaScript agents running Python triks.

Usage

No special code is required. The gateway automatically handles runtime detection and worker management:

import { TrikGateway } from '@trikhub/gateway'
 
const gateway = new TrikGateway()
await gateway.loadTriksFromConfig()
 
// Works regardless of whether the trik is JS or Python
const result = await gateway.execute(
  '@molefas/python-analyzer',  // A Python trik
  'analyze',
  { data: 'some input' }
)

Runtime Detection

The gateway determines a trik’s runtime from its manifest:

{
  "entry": {
    "module": "./graph.py",
    "export": "graph",
    "runtime": "python"
  }
}

If runtime is not specified, it defaults to "node".

Storage Proxy

When a cross-language trik uses storage, the calls are transparently proxied back to the main gateway process:

Python Agent                     Node.js Worker
     │                                │
     │  ◄─── storage.get("key") ────  │
     │                                │
     │  ───── { value: ... } ───────► │
     │                                │

This ensures all triks share the same SQLite database, regardless of their runtime.

Requirements

For JavaScript Agents Running Python Triks

• Python 3.9 or later installed
• The trikhub Python package: pip install trikhub

For Python Agents Running JavaScript Triks

• Node.js 18 or later installed
• The @trikhub/worker-js package (installed automatically via npx, or: npm install -g @trikhub/worker-js)

Worker Configuration

You can customize worker behavior when creating the gateway:

import { TrikGateway } from '@trikhub/gateway'
 
const gateway = new TrikGateway({
  pythonWorkerConfig: {
    pythonPath: '/usr/bin/python3.11',  // Custom Python path
    startupTimeoutMs: 15000,            // Worker startup timeout
    invokeTimeoutMs: 120000,            // Execution timeout
    debug: true                          // Enable debug logging
  }
})

Environment Variables

The gateway checks these environment variables to find the correct runtime:

The Python gateway auto-detects Node.js by searching PATH, NVM directories, and common installation locations.

Performance Considerations

• Worker startup: The first cross-language call spawns a worker (~100-500ms)
• Subsequent calls: Worker is reused, minimal overhead (~1-5ms)
• Worker lifecycle: Workers stay alive for the gateway’s lifetime
• Shutdown: Call gateway.shutdown() to clean up workers

Debugging

Enable debug mode to see worker communication:

const gateway = new TrikGateway({
  pythonWorkerConfig: { debug: true }
})

Output:

[PythonWorker:send] {"jsonrpc":"2.0","id":"abc123","method":"invoke",...}
[PythonWorker:recv] {"jsonrpc":"2.0","id":"abc123","result":{...}}

Next: Learn about the Security Model and type-directed privilege separation.