Skip to main content
Hopx uses a two-API architecture that separates sandbox lifecycle management from code execution. This design provides better scalability, security, and developer experience.

​
Two-API Model

​
1. Lifecycle API

Purpose: Manage sandboxes (create, delete, start, stop, pause, resume) Base URL: https://api.hopx.dev Authentication: API Key in X-API-Key header Used for:
  • Creating and deleting sandboxes
  • Listing sandboxes
  • Starting/stopping/pausing sandboxes
  • Managing templates
Example Request: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "X-API-Key: hopx_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "vcpu": 2,
    "memory_mb": 2048
  }'

​
2. VM Agent API

Purpose: Interact with code inside sandbox Base URL: https://{sandbox-id}.{region}.hopx.dev Authentication: API Key in X-API-Key header Used for:
  • Running code
  • File operations
  • Command execution
  • Process management
  • Metrics and observability
Example Request: 
curl -X POST https://sandbox-id.us-west-2.hopx.dev/v1/execute \
  -H "X-API-Key: hopx_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(\"Hello World\")"
  }'

​
How It Works

​
Step-by-Step Flow

  1. Create Sandbox: Your app calls the Lifecycle API to create a new sandbox
  2. Get Sandbox URL: Lifecycle API returns the sandbox ID and VM Agent URL
  3. Execute Code: Your app calls the VM Agent API to run code, manage files, etc.
  4. Manage Lifecycle: Your app calls the Lifecycle API to start, stop, pause, or delete the sandbox
The SDK handles both APIs automatically. You don’t need to manage API endpoints or authentication headers - just use the SDK methods.

​
SDK Abstraction

The SDK abstracts away the complexity of managing two APIs:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

# SDK handles Lifecycle API call
sandbox = Sandbox.create(template="code-interpreter")

# SDK handles VM Agent API call
result = sandbox.run_code("print('Hello')")

# SDK handles Lifecycle API call
sandbox.kill()  # Cleanup
Behind the scenes, the SDK:
  • Calls the Lifecycle API to create the sandbox
  • Stores the VM Agent URL internally
  • Routes code execution calls to the VM Agent API
  • Manages authentication headers automatically
  • Handles retries and error recovery

​
Benefits of Two-API Architecture

Separating lifecycle management from code execution allows each API to scale independently based on demand.
VM Agent API endpoints are sandbox-specific, providing better isolation and security boundaries.
Direct communication with VM Agent reduces latency for code execution operations.
Different APIs can be optimized for different use cases (lifecycle vs. execution).

​
Next Steps

Core Concepts

Back to Core Concepts overview

Sandbox Lifecycle

Learn about lifecycle management

Resources

Configure sandbox resources

Observability

Monitor and trace operations