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

> Official Python SDK for HopX - Create and manage cloud sandboxes in Python. Install the SDK, authenticate with your API key, and start creating sandboxes, executing code, managing files, and automating desktop interactions. Complete reference with code examples for all SDK methods and classes.

**Version:** 0.3.0\
**Last Verified:** 2025-01-27\
**Package:** `hopx-ai` on [PyPI](https://pypi.org/project/hopx-ai/)

## What is the Python SDK?

The HopX Python SDK provides a simple, powerful interface for creating and managing cloud sandboxes directly from your Python applications. Build AI agents, run untrusted code securely, execute tests in isolation, or process data with rich output capture—all with a clean, Pythonic API.

The SDK is a thin wrapper around the HopX REST API that handles authentication, request formatting, error translation, and response parsing automatically, giving you a better developer experience than working with the raw API.

## Target Audience

This SDK is designed for:

* **Backend Python developers** using Python 3.8+ (CPython recommended)
* **Data scientists** working with Jupyter notebooks, pandas, matplotlib
* **AI/ML engineers** building agents that need secure code execution
* **DevOps engineers** creating isolated testing environments
* **Automation engineers** building workflows that require sandboxed execution

## Supported Runtimes

* **Python:** 3.8, 3.9, 3.10, 3.11, 3.12 (CPython)
* **Operating Systems:** Linux, macOS, Windows
* **Package Managers:** pip, poetry, pipenv, conda

## When to Use the SDK vs CLI vs Raw API

### Use the Python SDK when:

* ✅ You're building Python applications
* ✅ You want type hints and IDE autocomplete
* ✅ You prefer Pythonic error handling and exceptions
* ✅ You need async/await support (`AsyncSandbox`)
* ✅ You want automatic resource management (context managers)
* ✅ You're working with Python data structures (dicts, lists, models)

### 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
* ✅ You need interactive terminal sessions

### Use the Raw API when:

* ⚠️ You're building in a non-Python language
* ⚠️ You need fine-grained control over HTTP requests
* ⚠️ You're integrating with existing HTTP client libraries
* ⚠️ You need custom retry logic or connection pooling

<Note>
  The SDK is a thin wrapper around the HopX REST API. It handles authentication, request formatting, error translation, and response parsing automatically. For most Python use cases, the SDK provides a better developer experience.
</Note>

## Architecture

The SDK consists of two main classes:

* **`Sandbox`** - Synchronous sandbox client (blocking operations)
* **`AsyncSandbox`** - Asynchronous sandbox client (async/await)

Both classes provide the same functionality, with `AsyncSandbox` optimized for concurrent operations and async frameworks.

## Core Capabilities

The Python SDK provides:

* **Sandbox Management** - Create, connect, list, and delete sandboxes
* **Code Execution** - Run Python, JavaScript, Bash, Go, and more
* **Rich Outputs** - Capture matplotlib plots, pandas DataFrames, images
* **File Operations** - Read, write, list, upload, download files
* **Command Execution** - Run shell commands synchronously or in background
* **Environment Variables** - Set, get, update, and clear environment variables
* **Process Management** - List and manage running processes
* **Cache Management** - Monitor and clear execution result cache
* **Desktop Automation** - VNC access, mouse/keyboard control (Premium)
* **Template Building** - Create custom sandbox environments
* **WebSocket Streaming** - Real-time terminal and code execution streaming

## Quick Example

```python theme={null}
from hopx_ai import Sandbox

# Create a sandbox (~100ms)
sandbox = Sandbox.create(template="code-interpreter")

# Execute code
result = sandbox.run_code('print("Hello from HopX!")')
print(result.stdout)  # "Hello from HopX!\n"

# Cleanup
sandbox.kill()
```

## Next Steps

* **[Installation Guide](/sdk/python/installation)** - Install the SDK and set up your environment
* **[Quickstart](/sdk/python/quickstart)** - Get your first sandbox running in minutes
* **[API Reference](/sdk/python/sandbox)** - Complete class and method documentation

## Related

* [JavaScript SDK](/sdk/javascript/introduction) - Official JavaScript/TypeScript SDK
* [CLI Reference](/cli/introduction) - Command-line interface for HopX
* [API Reference](/api/introduction) - Raw REST API documentation
* [Core Concepts](/core-concepts/sandboxes/creating) - Learn about sandboxes, execution, and more