Create Sandbox

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

Parameter	Type	Required	Description
`template_id`	string or integer	Yes*	Template ID to use
`template_name`	string	Yes*	Template name (alternative to `template_id`)
`region`	string	No	Preferred region (e.g., `us-east`, `eu-west`)
`timeout_seconds`	integer	No	Auto-kill timeout in seconds
`internet_access`	boolean	No	Enable internet access (default: `true`)
`env_vars`	object	No	Environment 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

Field	Type	Description
`id`	string	Sandbox ID (use for all subsequent operations)
`status`	string	Current sandbox status (`creating`, `running`, etc.)
`public_host`	string	VM Agent API base URL for this sandbox
`direct_url`	string	Alternative VM Agent API URL (same as `public_host`)
`template_id`	string	Template ID used to create sandbox
`template_name`	string	Template name
`resources`	object	Allocated resources (from template)
`auth_token`	string	JWT token for VM Agent API authentication
`token_expires_at`	string	ISO 8601 timestamp when token expires

Status Codes

Code	Description
`201`	Sandbox created successfully
`400`	Invalid request (missing template, invalid timeout, etc.)
`401`	Authentication required
`402`	Payment required (insufficient balance)
`404`	Template not found
`503`	Service 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"
  }'

SDK: Sandbox.create() - Python SDK method
Get Sandbox - Retrieve sandbox information
List Sandboxes - Query all your sandboxes
VM Agent API - Execute code in your new sandbox
CLI Sandbox Commands - Manage sandboxes from CLI

Next Steps

Get Sandbox - Retrieve sandbox information
List Sandboxes - Query all your sandboxes
VM Agent API - Execute code in your new sandbox

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (201 Created)

Response Fields

Status Codes

Errors

Template Not Found (404)

Invalid Request (400)

Service Unavailable (503)

Use Cases

Quick Code Execution

Long-Running Job

Region-Specific Deployment

Next Steps

​Endpoint

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (201 Created)

​Response Fields

​Status Codes

​Errors

​Template Not Found (404)

​Invalid Request (400)

​Service Unavailable (503)

​Use Cases

​Quick Code Execution

​Long-Running Job

​Region-Specific Deployment

​Related

​Next Steps

Endpoint

Request

Headers

Body Parameters

Example Request

Response

Success (201 Created)

Response Fields

Status Codes

Errors

Template Not Found (404)

Invalid Request (400)

Service Unavailable (503)

Use Cases

Quick Code Execution

Long-Running Job

Region-Specific Deployment

Related

Next Steps