Sandbox Data Models

​

Overview

​

Import

from hopx_ai import (
    SandboxInfo,
    Template as SandboxTemplate,
    ExecutionResult,
    CommandResult,
    FileInfo,
    RichOutput,
    VNCInfo,
    WindowInfo,
    RecordingInfo,
    DisplayInfo
)

​

Core Models

​

SandboxInfo

• 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

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

​

Template

• 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

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

​

ExecutionResult

• 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.)

• rich_count (int): Number of rich outputs

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

​

CommandResult

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

• success (bool): Whether command succeeded (exit_code == 0)

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

​

FileInfo

• 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

• 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

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

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

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

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

​

WindowInfo

• 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

• 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

• is_recording (bool): Whether recording is active
• is_ready (bool): Whether recording is ready

​

DisplayInfo

• width (int): Display width
• height (int): Display height
• depth (int): Color depth

• resolution (Tuple[int, int]): Resolution tuple

​

Resource Models

​

Resources

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

​

TemplateResources

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

​

Related Classes

• Errors - Error classes and exception handling
• Sandbox - Use models with sandbox operations

​

See Also

• Errors - Learn about error handling
• Core Concepts - Learn about core concepts

​

Next Steps

• Sandbox Operations - Use models in practice
• Error Handling - Type-safe error handling
• Quickstart Guide - Get started with the SDK
• CLI Reference - Use HopX from the command line
• Python Type Hints - Learn more about type hints