Skip to main content
The VM Agent API runs inside each sandbox and provides endpoints for code execution, file operations, command execution, desktop automation, and observability. Each sandbox has its own VM Agent API instance.

​
Base URL

Each sandbox has a unique VM Agent API URL: 
https://{sandbox_id}.hopx.dev
For example: 
https://sandbox_abc123xyz.hopx.dev
The base URL is returned in the public_host or direct_url field when you create a sandbox.

​
Authentication

All VM Agent API requests require a JWT token. This token is automatically generated when you create a sandbox: 
curl -X POST https://sandbox_abc123xyz.hopx.dev/execute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello World\")",
    "language": "python"
  }'
The JWT token:
  • Is returned in the auth_token field when creating a sandbox
  • Expires after a set time (check token_expires_at)
  • Can be refreshed using the Control Plane API

​
What You Can Do

​
Code Execution

  • Synchronous execution - Execute code and wait for results
  • Rich output capture - Capture matplotlib plots, pandas DataFrames, and visualizations
  • Background execution - Run long-running tasks asynchronously
  • Async execution - Execute code with webhook callbacks
  • Process management - List and kill running processes

​
Command Execution

  • Run commands - Execute shell commands synchronously
  • Background commands - Run long-running commands asynchronously

​
File Operations

  • Read/write files - Manage files in the sandbox
  • List directories - Browse filesystem
  • Upload/download - Transfer files to/from sandbox
  • File watching - Monitor file changes

​
Environment Variables

  • Get/set variables - Manage environment variables
  • Update variables - Merge or replace variables
  • Clear variables - Remove all variables

​
Desktop Automation

  • VNC access - Remote desktop via VNC
  • Mouse/keyboard control - Automate user interactions
  • Screenshots - Capture screen images
  • Screen recording - Record desktop sessions
  • Window management - Control application windows

​
Observability

  • Metrics - CPU, memory, disk usage
  • Processes - System and background processes
  • Cache - Execution result cache statistics
  • Terminal - Interactive terminal via WebSocket

​
API Endpoints

​
Code Execution

EndpointMethodDescription
/executePOSTExecute code synchronously
/execute/richPOSTExecute with rich output capture
/execute/backgroundPOSTExecute in background
/execute/asyncPOSTExecute with webhook callback
/execute/processesGETList background processes
/execute/killDELETEKill a background process

​
Commands

EndpointMethodDescription
/commands/runPOSTRun shell command
/commands/backgroundPOSTRun command in background

​
Files

EndpointMethodDescription
/files/readGETRead file contents
/files/writePOSTWrite file contents
/files/listGETList directory contents
/files/existsGETCheck if file exists
/files/removeDELETEDelete file or directory
/files/mkdirPOSTCreate directory

​
Environment

EndpointMethodDescription
/envGETGet all environment variables
/envPUTReplace all environment variables
/envPATCHUpdate environment variables
/envDELETEClear all environment variables

​
Desktop

EndpointMethodDescription
/desktop/vncPOSTStart/stop VNC server
/desktop/mousePOSTControl mouse
/desktop/keyboardPOSTControl keyboard
/desktop/clipboardGET/POSTManage clipboard
/desktop/screenshotPOSTTake screenshot
/desktop/recordingPOSTStart/stop recording
/desktop/windowsGETList windows
/desktop/displayGET/POSTManage display

​
Observability

EndpointMethodDescription
/systemGETGet system metrics
/processesGETList system processes
/cacheGETGet cache statistics
/cache/clearPOSTClear cache
/terminalWebSocketInteractive terminal

​
Response Format

All responses use JSON:

​
Success Response

{
  "success": true,
  "stdout": "Hello World\n",
  "stderr": "",
  "exit_code": 0
}

​
Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

​
Status Codes

CodeDescription
200Success
400Bad Request
401Unauthorized (invalid JWT)
404Not Found
500Internal Server Error

​
Supported Languages

The VM Agent supports multiple programming languages:
  • Python - Python 3.x with common packages
  • JavaScript - Node.js runtime
  • Bash - Shell scripting
  • Go - Go runtime (if available in template)

​
Next Steps