Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt

Use this file to discover all available pages before exploring further.

Build a production-ready plugin system that safely executes untrusted code from third-party developers. This cookbook demonstrates how to create a plugin marketplace with security isolation using HopX.

​
Overview

Plugin systems allow third-party developers to extend platform functionality. The system must execute untrusted code safely, enforce permissions, control API access, and maintain complete isolation between plugins.

​
Prerequisites

  • HopX API key (Get one here)
  • Python 3.8+ or Node.js 16+
  • Understanding of security isolation
  • Basic knowledge of permission systems

​
Architecture

┌──────────────┐
│   Plugin     │ Untrusted code
└──────┬───────┘
       │
       ▼
┌─────────────────┐
│  Plugin         │ Validate, isolate
│   Manager       │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Isolated        │ One per plugin
│  Sandbox         │
└─────────────────┘

​
Implementation

​
Step 1: Plugin Execution with Isolation

Execute plugins in isolated sandboxes: 
from hopx_ai import Sandbox
import os
from typing import Dict, Any, List

class Plugin:
    def __init__(self, plugin_id: str, code: str, permissions: List[str]):
        self.plugin_id = plugin_id
        self.code = code
        self.permissions = permissions

class PluginSystem:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.plugins = {}
        self.plugin_sandboxes = {}
    
    def register_plugin(self, plugin: Plugin):
        """Register a plugin"""
        self.plugins[plugin.plugin_id] = plugin
    
    def execute_plugin(self, plugin_id: str, context: Dict[str, Any] = None) -> Dict[str, Any]:
        """Execute plugin in isolated sandbox"""
        if plugin_id not in self.plugins:
            return {
                "success": False,
                "error": f"Plugin {plugin_id} not found"
            }
        
        plugin = self.plugins[plugin_id]
        sandbox = None
        
        try:
            # Create fresh sandbox for each execution
            sandbox = Sandbox.create(
                template="code-interpreter",
                api_key=self.api_key,
                timeout_seconds=60
            )
            
            # Set up plugin environment with limited permissions
            env_vars = {
                "PLUGIN_ID": plugin_id,
                "PERMISSIONS": ",".join(plugin.permissions)
            }
            sandbox.env.set_all(env_vars)
            
            # Add context if provided
            if context:
                for key, value in context.items():
                    sandbox.env.set(f"CONTEXT_{key}", str(value))
            
            # Execute plugin code
            result = sandbox.run_code(plugin.code, timeout=30)
            
            return {
                "success": result.success,
                "stdout": result.stdout,
                "stderr": result.stderr,
                "plugin_id": plugin_id
            }
        except Exception as e:
            return {
                "success": False,
                "error": str(e),
                "plugin_id": plugin_id
            }
        finally:
            if sandbox:
                sandbox.kill()  # Always cleanup
    
    def cleanup_all(self):
        """Clean up all plugin resources"""
        for sandbox in self.plugin_sandboxes.values():
            sandbox.kill()
        self.plugin_sandboxes.clear()

# Usage
system = PluginSystem(api_key=os.getenv("HOPX_API_KEY"))

# Register plugin
system.register_plugin(Plugin(
    plugin_id="calculator",
    code="result = 2 + 2\nprint(f'Result: {result}')",
    permissions=["compute"]
))

# Execute
result = system.execute_plugin("calculator")
print(result)

system.cleanup_all()

​
Best Practices

Always execute plugins in fresh, isolated sandboxes. Never trust plugin code or allow plugins to access system resources.
  1. Complete Isolation: One sandbox per plugin execution
  2. Permission System: Enforce permissions strictly
  3. Code Validation: Validate plugin code before execution
  4. Resource Limits: Set strict resource limits

​
Next Steps

  1. Implement permission system
  2. Add plugin marketplace features
  3. Create plugin validation
  4. Implement plugin versioning
  5. Add plugin monitoring