Skip to main content
Version: 0.3.0
Last Verified: 2025-01-27
Package: hopx-ai on PyPI

​
Overview

The Terminal resource provides interactive terminal access via WebSocket. Use this resource when you need interactive shell access, real-time terminal output, or terminal resizing capabilities.
Requires websockets library: pip install websockets

​
Access

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")
terminal = sandbox.terminal  # Lazy-loaded

​
Methods

​
connect

Connect to interactive terminal. 
async terminal.connect(*, timeout=30) -> WebSocketClientProtocol
Parameters:
  • timeout (int, optional): Connection timeout in seconds (default: 30)
Returns: WebSocketClientProtocol - WebSocket connection object Example: 
import asyncio

async def use_terminal():
    ws = await sandbox.terminal.connect()
    # Use terminal...
    await ws.close()

asyncio.run(use_terminal())

​
send_input

Send input to terminal. 
async terminal.send_input(ws, data) -> None
Parameters:
  • ws (WebSocketClientProtocol): WebSocket connection
  • data (str or bytes): Input data to send
Example: 
await sandbox.terminal.send_input(ws, "echo 'Hello'\n")

​
resize

Resize terminal window. 
async terminal.resize(ws, cols, rows) -> None
Parameters:
  • ws (WebSocketClientProtocol): WebSocket connection
  • cols (int): Number of columns
  • rows (int): Number of rows
Example: 
await sandbox.terminal.resize(ws, 80, 24)

​
iter_output

Iterate over terminal output messages. 
async terminal.iter_output(ws) -> AsyncIterator[Dict[str, Any]]
Parameters:
  • ws (WebSocketClientProtocol): WebSocket connection
Returns: AsyncIterator[Dict[str, Any]] - Iterator of message dictionaries Example: 
async for message in sandbox.terminal.iter_output(ws):
    if message.get('type') == 'stdout':
        print(message.get('data', ''), end='')

​
Examples

​
Example 1: Basic Terminal Usage

import asyncio
from hopx_ai import Sandbox

async def main():
    sandbox = Sandbox.create(template="code-interpreter")
    
    # Connect to terminal
    ws = await sandbox.terminal.connect()
    
    # Send command
    await sandbox.terminal.send_input(ws, "echo 'Hello, Terminal!'\n")
    
    # Read output
    async for message in sandbox.terminal.iter_output(ws):
        if message.get('type') == 'stdout':
            print(message.get('data', ''), end='')
            break  # Exit after first output
    
    await ws.close()
    sandbox.kill()

asyncio.run(main())

​
Example 2: Interactive Terminal Session

import asyncio
from hopx_ai import Sandbox

async def main():
    sandbox = Sandbox.create(template="code-interpreter")
    ws = await sandbox.terminal.connect()
    
    # Resize terminal
    await sandbox.terminal.resize(ws, 120, 40)
    
    # Send multiple commands
    commands = [
        "pwd\n",
        "ls -la\n",
        "echo 'Done'\n"
    ]
    
    for cmd in commands:
        await sandbox.terminal.send_input(ws, cmd)
        # Read output
        async for message in sandbox.terminal.iter_output(ws):
            if message.get('type') == 'stdout':
                print(message.get('data', ''), end='')
            elif message.get('type') == 'done':
                break
    
    await ws.close()
    sandbox.kill()

asyncio.run(main())

​
See Also

​
Next Steps