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

# Sandbox Data Models

> Data models and type definitions for the HopX Python SDK. Understand sandbox objects, execution results, file metadata, template structures, and other data models used throughout the SDK. Essential for working with SDK responses and building type-safe applications. Includes complete model reference and field descriptions.

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

## Overview

The Python SDK provides data models for all API responses and objects. These models provide type safety, convenience methods, and clear documentation of data structures.

## Import

```python theme={null}
from hopx_ai import (
    SandboxInfo,
    Template as SandboxTemplate,
    ExecutionResult,
    CommandResult,
    FileInfo,
    RichOutput,
    VNCInfo,
    WindowInfo,
    RecordingInfo,
    DisplayInfo
)
```

## Core Models

### `SandboxInfo`

Sandbox information model.

**Fields:**

* `sandbox_id` (`str`): Unique sandbox identifier
* `template_id` (`str`): Template ID used to create sandbox
* `template_name` (`str`): Template name
* `organization_id` (`str`): Organization ID
* `node_id` (`str`): Node ID
* `region` (`str`): Deployment region
* `status` (`str`): Sandbox status (`"running"`, `"stopped"`, `"paused"`, `"creating"`)
* `public_host` (`str`): Public hostname
* `resources` (`Resources`): Resource specifications
* `started_at` (`datetime`): Start timestamp
* `end_at` (`datetime`, optional): End timestamp
* `created_at` (`datetime`): Creation timestamp

**Example:**

```python theme={null}
info = sandbox.get_info()
print(f"ID: {info.sandbox_id}")
print(f"Status: {info.status}")
print(f"Host: {info.public_host}")
```

***

### `Template`

Template information model.

**Fields:**

* `id` (`str`): Template ID
* `name` (`str`): Template name
* `display_name` (`str`): Display name
* `description` (`str`): Template description
* `category` (`str`): Template category
* `language` (`str`): Primary language
* `icon` (`str`, optional): Icon URL
* `default_resources` (`TemplateResources`): Default resource specifications
* `min_resources` (`TemplateResources`): Minimum resources
* `max_resources` (`TemplateResources`): Maximum resources
* `features` (`List[str]`): Available features
* `tags` (`List[str]`): Template tags
* `popularity_score` (`float`): Popularity score
* `docs_url` (`str`, optional): Documentation URL
* `is_active` (`bool`): Whether template is active
* `status` (`str`): Template status

**Example:**

```python theme={null}
template = Sandbox.get_template("code-interpreter")
print(f"Name: {template.name}")
print(f"Resources: {template.default_resources.vcpu} vCPU")
```

***

### `ExecutionResult`

Result of code execution.

**Fields:**

* `success` (`bool`): Whether execution succeeded
* `stdout` (`str`): Standard output
* `stderr` (`str`): Standard error
* `exit_code` (`int`): Exit code (0 = success)
* `execution_time` (`float`): Execution time in seconds
* `rich_outputs` (`List[RichOutput]`): Rich outputs (plots, DataFrames, etc.)

**Properties:**

* `rich_count` (`int`): Number of rich outputs

**Example:**

```python theme={null}
result = sandbox.run_code("print('Hello')")
print(result.stdout)
print(f"Success: {result.success}")
print(f"Rich outputs: {result.rich_count}")
```

***

### `CommandResult`

Result of command execution.

**Fields:**

* `stdout` (`str`): Standard output
* `stderr` (`str`): Standard error
* `exit_code` (`int`): Exit code
* `execution_time` (`float`): Execution time in seconds

**Properties:**

* `success` (`bool`): Whether command succeeded (`exit_code == 0`)

**Example:**

```python theme={null}
result = sandbox.commands.run("ls -la")
print(result.stdout)
print(f"Success: {result.success}")
```

***

### `FileInfo`

File or directory information.

**Fields:**

* `name` (`str`): File or directory name
* `path` (`str`): Full path
* `size` (`int`): Size in bytes
* `is_directory` (`bool`): Whether it's a directory
* `permissions` (`str`): File permissions
* `modified_time` (`datetime`): Last modification time

**Properties:**

* `is_file` (`bool`): Whether it's a file
* `is_dir` (`bool`): Whether it's a directory
* `size_kb` (`float`): Size in kilobytes
* `size_mb` (`float`): Size in megabytes

**Example:**

```python theme={null}
items = sandbox.files.list("/workspace")
for item in items:
    if item.is_directory:
        print(f"Directory: {item.name}")
    else:
        print(f"File: {item.name} ({item.size_kb:.2f} KB)")
```

***

### `RichOutput`

Rich output from code execution (plots, DataFrames, etc.).

**Fields:**

* `type` (`str`): Output type (`"plot"`, `"dataframe"`, `"html"`, etc.)
* `data` (`str` or `bytes`): Output data
* `metadata` (`Dict[str, Any]`): Additional metadata
* `timestamp` (`datetime`): Output timestamp

**Example:**

```python theme={null}
result = sandbox.run_code("import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('/tmp/plot.png')")
for output in result.rich_outputs:
    if output.type == "plot":
        print(f"Plot generated at {output.timestamp}")
```

***

## Desktop Models

### `VNCInfo`

VNC server information.

**Fields:**

* `running` (`bool`): Whether VNC is running
* `display` (`int`): Display number
* `port` (`int`): VNC port
* `url` (`str`): VNC URL
* `password` (`str`): VNC password

***

### `WindowInfo`

Window information.

**Fields:**

* `id` (`str`): Window ID
* `title` (`str`): Window title
* `x` (`int`): X coordinate
* `y` (`int`): Y coordinate
* `width` (`int`): Window width
* `height` (`int`): Window height
* `desktop` (`int`): Desktop number
* `pid` (`int`): Process ID

***

### `RecordingInfo`

Screen recording information.

**Fields:**

* `recording_id` (`str`): Recording ID
* `status` (`str`): Recording status
* `fps` (`int`): Frames per second
* `format` (`str`): Video format
* `duration` (`float`): Duration in seconds
* `file_size` (`int`): File size in bytes

**Properties:**

* `is_recording` (`bool`): Whether recording is active
* `is_ready` (`bool`): Whether recording is ready

***

### `DisplayInfo`

Display information.

**Fields:**

* `width` (`int`): Display width
* `height` (`int`): Display height
* `depth` (`int`): Color depth

**Properties:**

* `resolution` (`Tuple[int, int]`): Resolution tuple

***

## Resource Models

### `Resources`

Resource specifications.

**Fields:**

* `vcpu` (`int`): Number of vCPUs
* `memory_mb` (`int`): Memory in megabytes
* `disk_mb` (`int`): Disk space in megabytes

***

### `TemplateResources`

Template resource specifications.

**Fields:**

* `vcpu` (`int`): Number of vCPUs
* `memory_mb` (`int`): Memory in megabytes
* `disk_gb` (`int`): Disk space in gigabytes

***

## Related Classes

* **[Errors](/sdk/python/errors)** - Error classes and exception handling
* **[Sandbox](/sdk/python/sandbox)** - Use models with sandbox operations

## See Also

* [Errors](/sdk/python/errors) - Learn about error handling
* [Core Concepts](/core-concepts) - Learn about core concepts

## Next Steps

Now that you understand data models, explore:

* [Sandbox Operations](/sdk/python/sandbox) - Use models in practice
* [Error Handling](/sdk/python/errors) - Type-safe error handling
* [Quickstart Guide](/sdk/python/quickstart) - Get started with the SDK
* **[CLI Reference](/cli/introduction)** - Use HopX from the command line
* [Python Type Hints](https://docs.python.org/3/library/typing.html) - Learn more about type hints