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

# Terminal Access

> Interactive terminal resource for WebSocket-based sandbox terminal access in HopX using the Python SDK. Complete reference for the Terminal class including methods for connecting to interactive terminals, executing commands in real-time, and streaming terminal output. Includes code examples for terminal automation.

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

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

<Note>
  Requires `websockets` library: `pip install websockets`
</Note>

## Access

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

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

## Methods

### `connect`

Connect to interactive terminal.

```python theme={null}
async terminal.connect(*, timeout=30) -> WebSocketClientProtocol
```

**Parameters:**

* `timeout` (`int`, optional): Connection timeout in seconds (default: `30`)

**Returns:** `WebSocketClientProtocol` - WebSocket connection object

**Example:**

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

```python theme={null}
async terminal.send_input(ws, data) -> None
```

**Parameters:**

* `ws` (`WebSocketClientProtocol`): WebSocket connection
* `data` (`str` or `bytes`): Input data to send

**Example:**

```python theme={null}
await sandbox.terminal.send_input(ws, "echo 'Hello'\n")
```

***

### `resize`

Resize terminal window.

```python theme={null}
async terminal.resize(ws, cols, rows) -> None
```

**Parameters:**

* `ws` (`WebSocketClientProtocol`): WebSocket connection
* `cols` (`int`): Number of columns
* `rows` (`int`): Number of rows

**Example:**

```python theme={null}
await sandbox.terminal.resize(ws, 80, 24)
```

***

### `iter_output`

Iterate over terminal output messages.

```python theme={null}
async terminal.iter_output(ws) -> AsyncIterator[Dict[str, Any]]
```

**Parameters:**

* `ws` (`WebSocketClientProtocol`): WebSocket connection

**Returns:** `AsyncIterator[Dict[str, Any]]` - Iterator of message dictionaries

**Example:**

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

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

```python theme={null}
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())
```

***

## Related Classes

* **[Sandbox](/sdk/python/sandbox)** - Main sandbox class
* **[Core Concepts: Terminal](/core-concepts/terminal)** - Learn about terminal access

## See Also

* [Sandbox Class](/sdk/python/sandbox) - Access terminal via `sandbox.terminal`
* [Terminal Documentation](/core-concepts/terminal) - Detailed terminal documentation

## Related

* **[WebSocket Terminal](/core-concepts/terminal/websocket)** - Learn about terminal access
* **[Running Commands](/core-concepts/commands/running)** - Execute shell commands synchronously
* **[Sandbox Class](/sdk/python/sandbox)** - Access terminal via `sandbox.terminal`

## Next Steps

* Learn about [WebSocket Terminal](/core-concepts/terminal/websocket) for interactive terminal access
* Explore [Running Commands](/core-concepts/commands/running) for synchronous command execution
* Review [Background Commands](/core-concepts/commands/background) for non-blocking execution
* **[CLI Terminal](/cli/commands/terminal)** - Access terminal from CLI