Skip to main content
Create a new sandbox from a template. The sandbox will be provisioned with resources (vCPU, memory, disk) defined by the template.

​
Endpoint

POST /v1/sandboxes

​
Request

​
Headers

Authorization: Bearer $HOPX_API_KEY
Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
template_idstring or integerYes*Template ID to use
template_namestringYes*Template name (alternative to template_id)
regionstringNoPreferred region (e.g., us-east, eu-west)
timeout_secondsintegerNoAuto-kill timeout in seconds
internet_accessbooleanNoEnable internet access (default: true)
env_varsobjectNoEnvironment variables to set in sandbox
Either template_id or template_name must be provided. Resources (vcpu, memory, disk) are always loaded from the template - you cannot specify custom resources.

​
Example Request

curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600,
    "internet_access": true,
    "env_vars": {
      "MY_VAR": "my_value",
      "API_KEY": "secret123"
    }
  }'
Replace $HOPX_API_KEY with your actual API key from console.hopx.dev, or set it as an environment variable: export HOPX_API_KEY="your-API key-here"
Or using template name: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "timeout_seconds": 3600
  }'
Replace $HOPX_API_KEY with your actual API key from console.hopx.dev, or set it as an environment variable: export HOPX_API_KEY="your-API key-here"

​
Response

​
Success (201 Created)

{
  "id": "sandbox_abc123xyz",
  "object": "sandbox",
  "status": "running",
  "public_host": "https://sandbox_abc123xyz.hopx.dev",
  "direct_url": "https://sandbox_abc123xyz.hopx.dev",
  "template_id": "73",
  "template_name": "code-interpreter",
  "organization_id": 123,
  "node_id": "node_xyz789",
  "region": "us-east",
  "resources": {
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_mb": 10240
  },
  "internet_access": true,
  "timeout_seconds": 3600,
  "expires_at": "2025-01-29T00:00:00Z",
  "created_at": "2025-01-28T00:00:00Z",
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}

​
Response Fields

FieldTypeDescription
idstringSandbox ID (use for all subsequent operations)
statusstringCurrent sandbox status (creating, running, etc.)
public_hoststringVM Agent API base URL for this sandbox
direct_urlstringAlternative VM Agent API URL (same as public_host)
template_idstringTemplate ID used to create sandbox
template_namestringTemplate name
resourcesobjectAllocated resources (from template)
auth_tokenstringJWT token for VM Agent API authentication
token_expires_atstringISO 8601 timestamp when token expires

​
Status Codes

CodeDescription
201Sandbox created successfully
400Invalid request (missing template, invalid timeout, etc.)
401Authentication required
402Payment required (insufficient balance)
404Template not found
503Service unavailable (no available nodes)

​
Errors

​
Template Not Found (404)

{
  "error": "Template not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}
Cause: The specified template_id or template_name doesn’t exist. Fix: List available templates using GET /v1/templates to find valid template IDs or names.

​
Invalid Request (400)

{
  "error": "Invalid request: timeout_seconds must be positive",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
Cause: Invalid parameter value (e.g., negative timeout, missing template). Fix: Verify all parameters meet requirements:
  • timeout_seconds must be positive
  • Either template_id or template_name must be provided
  • env_vars must be a valid object

​
Service Unavailable (503)

{
  "error": "Service unavailable: no available nodes",
  "code": "SERVICE_UNAVAILABLE",
  "request_id": "req_abc123"
}
Cause: No compute nodes are available to provision the sandbox. Fix: Retry the request after a few moments. This is usually temporary.

​
Use Cases

​
Quick Code Execution

Create a sandbox for quick code execution: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "timeout_seconds": 300
  }'

​
Long-Running Job

Create a sandbox for a long-running task: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 7200,
    "env_vars": {
      "DATABASE_URL": "postgres://...",
      "API_KEY": "secret"
    }
  }'

​
Region-Specific Deployment

Create a sandbox in a specific region: 
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-interpreter",
    "region": "eu-west"
  }'

​
Next Steps