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.
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
https://sandbox_abc123xyz.hopx.dev
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"
}'
- 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
| Endpoint | Method | Description |
|---|
/execute | POST | Execute code synchronously |
/execute/rich | POST | Execute with rich output capture |
/execute/background | POST | Execute in background |
/execute/async | POST | Execute with webhook callback |
/execute/processes | GET | List background processes |
/execute/kill | DELETE | Kill a background process |
Commands
| Endpoint | Method | Description |
|---|
/commands/run | POST | Run shell command |
/commands/background | POST | Run command in background |
Files
| Endpoint | Method | Description |
|---|
/files/read | GET | Read file contents |
/files/write | POST | Write file contents |
/files/list | GET | List directory contents |
/files/exists | GET | Check if file exists |
/files/remove | DELETE | Delete file or directory |
/files/mkdir | POST | Create directory |
Environment
| Endpoint | Method | Description |
|---|
/env | GET | Get all environment variables |
/env | PUT | Replace all environment variables |
/env | PATCH | Update environment variables |
/env | DELETE | Clear all environment variables |
Desktop
| Endpoint | Method | Description |
|---|
/desktop/vnc | POST | Start/stop VNC server |
/desktop/mouse | POST | Control mouse |
/desktop/keyboard | POST | Control keyboard |
/desktop/clipboard | GET/POST | Manage clipboard |
/desktop/screenshot | POST | Take screenshot |
/desktop/recording | POST | Start/stop recording |
/desktop/windows | GET | List windows |
/desktop/display | GET/POST | Manage display |
Observability
| Endpoint | Method | Description |
|---|
/system | GET | Get system metrics |
/processes | GET | List system processes |
/cache | GET | Get cache statistics |
/cache/clear | POST | Clear cache |
/terminal | WebSocket | Interactive terminal |
Success Response
{
"success": true,
"stdout": "Hello World\n",
"stderr": "",
"exit_code": 0
}
Error Response
{
"error": "Error message",
"code": "ERROR_CODE"
}
Status Codes
| Code | Description |
|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized (invalid JWT) |
| 404 | Not Found |
| 500 | Internal 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
