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.

Get up and running with the HopX API in minutes. This quickstart walks you through creating your first sandbox, executing code, and cleaning up.

​
What You’ll Learn

In this quickstart, you’ll learn how to:
  • Authenticate with the HopX API using API keys
  • Create sandboxes using the Control Plane API
  • Execute code using the VM Agent API
  • Handle API responses and extract results
  • Delete sandboxes to free resources
  • Use common API patterns and variations

​
Prerequisites

Before you begin, you’ll need:
  • An API key from console.hopx.dev
  • curl installed (or any HTTP client)
  • Basic familiarity with REST APIs

​
Step 1: Set Your API key

Set your API key as an environment variable: 
export HOPX_API_KEY="hopx_live_YOUR_KEY_ID.YOUR_SECRET"
Replace YOUR_KEY_ID and YOUR_SECRET with your actual API key from the dashboard.

​
Step 2: Create a Sandbox

Create a sandbox from a pre-built template: 
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
  }'
Response: 
{
  "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,
  "region": "us-east",
  "resources": {
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_mb": 10240
  },
  "internet_access": true,
  "timeout_seconds": 3600,
  "created_at": "2025-01-28T00:00:00Z",
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}
Save the id and auth_token from the response. You’ll need them for the next steps.

​
Step 3: Execute Code

Execute Python code in your sandbox using the VM Agent API: 
curl -X POST https://sandbox_abc123xyz.hopx.dev/execute \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello from HopX!\")",
    "language": "python"
  }'
Response: 
{
  "success": true,
  "stdout": "Hello from HopX!\n",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 0.15
}

​
Step 4: Clean Up

Delete the sandbox when you’re done: 
curl -X DELETE https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY"
Response: 
{
  "status": "deleted",
  "id": "sandbox_abc123xyz",
  "request_id": "req_abc123"
}

​
What Just Happened?

  1. Created a sandbox - You spun up an isolated cloud environment from the code-interpreter template
  2. Executed code - You ran Python code in the sandbox and received the output
  3. Cleaned up - You deleted the sandbox to free resources
The sandbox was completely isolated - any code you run can’t access your local system or other sandboxes.

​
Next Steps

​
Common Variations

​
Create Sandbox with Environment Variables

curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "env_vars": {
      "MY_VAR": "my_value",
      "API_KEY": "secret123"
    }
  }'

​
Execute JavaScript Code

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"Hello from JavaScript!\");",
    "language": "javascript"
  }'

​
List All Sandboxes

curl https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY"

​
Troubleshooting

​
Error: 401 Unauthorized

Your API key is missing or invalid. Verify:
  • The HOPX_API_KEY environment variable is set correctly
  • You’re using the Authorization: Bearer header format
  • Your API key hasn’t been revoked in the dashboard

​
Error: 404 Template Not Found

The template ID doesn’t exist. Try:
  • Listing available templates: GET /v1/templates
  • Using a template name instead: "template_name": "code-interpreter"

​
Error: 503 Service Unavailable

No sandboxes are available at the moment. This is usually temporary. Try again in a few moments. For more help, see the Errors & Troubleshooting guide.