Cross-Environment Execution

TrikHub supports running triks written in different languages from any agent runtime. A JavaScript agent can execute Python 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    ┌─────────────────┐
│  JS Agent       │ <────────────────>  │  Python Worker  │
│  (TrikGateway)  │      stdin/stdout   │ (trikhub)       │
│                 │                     │                 │
└────────┬────────┘                     └────────┬────────┘
         │                                       │
    JS Triks                                Python Triks
    (in-process)                           (in-process)

The same applies in reverse for Python agents running JavaScript 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.initialize();
await gateway.loadTriksFromConfig();
 
// Route messages regardless of whether the trik is JS or Python
const result = await gateway.routeMessage('search for AI articles', sessionId);

Note: Cross-language execution uses the v2 handoff protocol. Both Python and JavaScript triks are fully supported in their respective gateways.

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:

JS Agent                        Python 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.10 or later installed
• The trikhub-worker Python package: python3 -m pip install trikhub

For Python Agents Running JavaScript Triks

• Node.js 22.5 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:

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.