> ## 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.

# Overview

> Execute code, manage files, and control sandbox resources with the HopX VM Agent API. Run code in multiple languages, perform file operations, execute shell commands, manage environment variables, and automate desktop interactions. Complete reference for all VM Agent API endpoints with authentication and examples.

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:

```bash theme={null}
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

| 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  |

## Response Format

All responses use JSON:

### Success Response

```json theme={null}
{
  "success": true,
  "stdout": "Hello World\n",
  "stderr": "",
  "exit_code": 0
}
```

### Error Response

```json theme={null}
{
  "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)

## Related

* **[SDK: File Operations](/sdk/python/files)** - Python SDK file operations
* **[SDK: Code Execution](/sdk/python/sandbox#run_code)** - Python SDK code execution
* **[SDK: Commands](/sdk/python/commands)** - Python SDK command execution
* **[Code Execution Concepts](/core-concepts/code-execution/synchronous)** - Learn about code execution
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Execute Code](/api/vm-agent/execute)** - Run code synchronously
* **[Rich Output](/api/vm-agent/execute-rich)** - Capture plots and visualizations
* **[Background Execution](/api/vm-agent/execute-background)** - Run long-running tasks
* **[File Operations](/api/vm-agent/read-file)** - Manage files in sandbox