Skip to main content
Create a new sandbox from a template. The sandbox will be created in the running state and ready to use.

​
Endpoint

POST /v1/sandboxes

​
Request

​
Headers

X-API-Key: your_api_key_here
Content-Type: application/json

​
Request Body

{
  "template_id": "52",
  "template_name": "code-interpreter",
  "region": "us-east",
  "timeout_seconds": 3600,
  "internet_access": true,
  "env_vars": {
    "API_KEY": "sk-test-123",
    "DEBUG": "true"
  }
}
Parameters:
ParameterTypeRequiredDescription
template_idstringYes*Template ID (alternative to template_name)
template_namestringYes*Template name (alternative to template_id)
regionstringNoPreferred region (auto-selected if not specified)
timeout_secondsintegerNoAuto-kill timeout in seconds (default: no timeout)
internet_accessbooleanNoEnable internet access (default: true)
env_varsobjectNoEnvironment variables to set in the sandbox
* Either template_id or template_name must be provided.

​
Response

​
Success (201 Created)

{
  "id": "1761048129dsaqav4n",
  "organization_id": "org-abc123",
  "status": "running",
  "public_host": "https://1761048129dsaqav4n.hopx.dev",
  "template_name": "code-interpreter",
  "created_at": "2025-01-15T10:30:00Z",
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2025-01-15T11:30:00Z",
  "resources": {
    "vcpu": 2,
    "memory_mb": 2048,
    "disk_gb": 10
  }
}

​
Error Responses

400 Bad Request: 
{
  "error": "Either template_id or template_name must be provided"
}
401 Unauthorized: 
{
  "error": "Unauthorized",
  "code": "AUTHENTICATION_ERROR"
}
429 Rate Limit: 
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

​
Examples

​
cURL

curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "52",
    "timeout_seconds": 3600,
    "internet_access": true,
    "env_vars": {
      "API_KEY": "sk-test-123"
    }
  }'

​
Python

import os
import requests

api_key = os.environ.get("HOPX_API_KEY")

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

data = {
    "template_id": "52",
    "timeout_seconds": 3600,
    "internet_access": True,
    "env_vars": {
        "API_KEY": "sk-test-123",
        "DEBUG": "true"
    }
}

response = requests.post(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers,
    json=data
)

if response.status_code == 201:
    sandbox = response.json()
    print(f"Created sandbox: {sandbox['id']}")
    print(f"Public host: {sandbox['public_host']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

​
JavaScript

const apiKey = process.env.HOPX_API_KEY;

const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_id: '52',
    timeout_seconds: 3600,
    internet_access: true,
    env_vars: {
      API_KEY: 'sk-test-123',
      DEBUG: 'true'
    }
  })
});

if (response.ok) {
  const sandbox = await response.json();
  console.log(`Created sandbox: ${sandbox.id}`);
  console.log(`Public host: ${sandbox.public_host}`);
} else {
  const error = await response.json();
  console.error('Error:', error);
}

​
Using Template Name

Instead of template_id, you can use template_name: cURL: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "vcpu": 2,
    "memory_mb": 2048
  }'
Python: 
data = {
    "template_name": "code-interpreter",
    "timeout_seconds": 3600
}

response = requests.post(
    "https://api.hopx.dev/v1/sandboxes",
    headers=headers,
    json=data
)
JavaScript: 
const response = await fetch('https://api.hopx.dev/v1/sandboxes', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template_name: 'code-interpreter',
    timeout_seconds: 3600
  })
});

​
Notes

  • The sandbox is created in the running state and ready to use immediately
  • The auth_token in the response is a JWT token for authenticating with the VM agent
  • Resources (vCPU, memory, disk) are loaded from the template - you cannot specify custom resources
  • To specify custom resources, create a template with the desired resources first
  • The public_host URL is the base URL for VM agent API calls