Skip to main content
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.