Skip to main content
The HopX REST API enables you to create, manage, and interact with cloud sandboxes programmatically. Use the API to build automation workflows, integrate sandbox execution into your applications, or create custom tooling on top of HopX.

​
What the API Does

The HopX API provides two main interfaces:

​
Control Plane API

The Control Plane API (https://api.hopx.dev) manages sandbox lifecycle and templates:
  • Create and manage sandboxes - Spin up isolated cloud environments from templates
  • Template management - List, view, and build custom templates
  • Real-time monitoring - Stream sandbox events and metrics via Server-Sent Events (SSE)
  • Resource management - Start, stop, pause, resume, and delete sandboxes

​
VM Agent API

The VM Agent API (sandbox-specific URLs) executes code and manages sandbox resources:
  • Code execution - Run Python, JavaScript, Bash, and Go code synchronously or asynchronously
  • File operations - Read, write, list, upload, and download files
  • Command execution - Run shell commands in the sandbox environment
  • Desktop automation - Control VNC, mouse, keyboard, screenshots, and screen recording
  • Observability - Monitor processes, metrics, cache, and terminal access

​
Main Resources

​
Sandboxes

Sandboxes are isolated cloud environments created from templates. Each sandbox has:
  • Unique ID - Identifier for all operations
  • Status - running, stopped, paused, creating
  • Resources - vCPU, memory, and disk allocated from template
  • Public URL - Accessible endpoint for VM Agent API
  • JWT Token - Authentication token for VM Agent API calls

​
Templates

Templates define the base environment for sandboxes:
  • Pre-built templates - Python, Node.js, Ubuntu, and more
  • Custom templates - Build your own with Docker images and build steps
  • Resource specifications - vCPU, memory, and disk limits
  • Features - Desktop support, internet access, pre-installed packages

​
When to Use the API vs SDK vs CLI

​
Use the REST API when:

  • ✅ You’re building in a language without an official SDK
  • ✅ You need fine-grained control over HTTP requests
  • ✅ You’re integrating with existing HTTP client libraries
  • ✅ You need custom retry logic or connection pooling
  • ✅ You’re building serverless functions or edge workers

​
Use the SDK when:

  • ✅ You’re building Python or JavaScript/TypeScript applications
  • ✅ You want type safety and IDE autocomplete
  • ✅ You prefer language-native error handling
  • ✅ You want automatic resource management

​
Use the CLI when:

  • ✅ You prefer command-line workflows
  • ✅ You’re scripting or automating from shell
  • ✅ You want quick one-off operations
  • ✅ You’re working in CI/CD pipelines

​
Typical Consumers

The HopX API is used by:
  • Backend developers - Integrating sandbox execution into applications
  • DevOps engineers - Automating infrastructure and testing workflows
  • AI/ML engineers - Running model training and inference in isolated environments
  • CI/CD pipelines - Executing tests and builds in clean sandboxes
  • Automation tools - Building custom tooling and workflows

​
Base URLs

​
Control Plane API

https://api.hopx.dev
All Control Plane endpoints are prefixed with /v1/: 
https://api.hopx.dev/v1/sandboxes
https://api.hopx.dev/v1/templates

​
VM Agent API

Each sandbox has its own VM Agent API endpoint: 
https://{sandbox_id}.hopx.dev
Or using the direct URL format: 
https://{port}-{vmId}.{serverId}.hopx.dev
The VM Agent base URL is returned in the public_host or direct_url field when creating a sandbox.

​
API Specification

The HopX API follows RESTful principles:
  • HTTP methods - GET, POST, PUT, DELETE for resource operations
  • JSON request/response - All request bodies and responses use JSON
  • Standard status codes - 200, 201, 400, 401, 404, 503, etc.
  • Error format - Consistent error response structure with codes and messages
An OpenAPI specification is available for the Control Plane API. The spec is kept in sync with the API implementation and can be used to generate client SDKs or mock servers.

​
Next Steps