Metadata-Version: 2.4
Name: gradio-terminal
Version: 1.0.0
Summary: A Gradio component that provides a fully functional terminal using xterm.js and PTY
Author: Po-Hsuan Huang
Author-email: Po-Hsuan Huang <aben20807@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/aben20807/gradio-terminal
Project-URL: Repository, https://github.com/aben20807/gradio-terminal
Project-URL: Issues, https://github.com/aben20807/gradio-terminal/issues
Keywords: gradio,terminal,xterm,pty,shell
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gradio>=6.3.0
Requires-Dist: flask>=3.1.2
Requires-Dist: flask-socketio>=5.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# Gradio Terminal

[![PyPI](https://img.shields.io/pypi/v/gradio-terminal?color=blue&style=flat&logo=pypi)](https://pypi.org/project/gradio-terminal/) [![PyPI Downloads](https://static.pepy.tech/badge/gradio-terminal)](https://pepy.tech/projects/gradio-terminal) [![GitHub license](https://img.shields.io/github/license/aben20807/gradio-terminal?color=blue)](LICENSE) [![Coding style](https://img.shields.io/badge/code%20style-black-1183C3.svg)](https://github.com/psf/black)

A Gradio component that provides a fully functional terminal in your browser. This package uses xterm.js on the frontend and a PTY on the backend to provide a real shell experience.

![Gradio Terminal](https://github.com/user-attachments/assets/8a4cc81a-07a4-4c56-a008-bd438eae50de)

## Installation

```bash
pip install gradio-terminal
```

## Quick Start

### Simple Usage

```python
import gradio as gr
from gradio_terminal import Terminal
demo = gr.Blocks()
with demo:
    terminal = Terminal()
demo.launch()
```

### Secure Terminal (No Sudo)

```python
import gradio as gr
from gradio_terminal import Terminal
demo = gr.Blocks()
with demo:
    terminal = Terminal(allow_sudo=False)  # Block sudo commands
demo.launch()
```

## API Reference

| Function | Parameters | Description |
|----------|------------|-------------|
| `launch_terminal()` | `port=5000`, `host="127.0.0.1"`, `command="bash"`, `share=False`, `allow_sudo=True`, `**launch_kwargs` | Launch a standalone Gradio app with a terminal. |
| `create_terminal_demo()` | `port=5000`, `host="127.0.0.1"`, `command="bash"`, `height=400`, `allow_sudo=True` | Create a Gradio Blocks demo with an embedded terminal. |
| `Terminal()` | `port=5000`, `host="127.0.0.1"`, `command="bash"`, `height=400`, `label=None`, `visible=True`, `elem_id=None`, `elem_classes=None`, `allow_sudo=True` | Create a terminal component for Gradio Blocks. |
| `TerminalServer()` | `port=5000`, `host="127.0.0.1"`, `command="bash"` | Low-level terminal server for custom integrations. |

### TerminalServer Methods

| Method | Description |
|--------|-------------|
| `start()` | Start the server and return the URL |
| `get_url()` | Get the terminal server URL |
| `stop()` | Stop the terminal server |

### Notes

- `allow_sudo`: Whether to allow sudo commands (default: True). When False, sudo commands are blocked with an error message.

## Security

This component provides shell access to your server. Use the `allow_sudo=False` parameter to block sudo commands for enhanced security:

```python
terminal = Terminal(allow_sudo=False)
```

## Requirements

- Python 3.8+
- Linux
- Dependencies: gradio, flask, flask-socketio

## Security Notice

This component provides shell access to your server. Use only in trusted environments.

## License

This project is licensed under the Apache-2.0 License.

## Acknowledgments

- [pyxtermjs](https://github.com/cs01/pyxtermjs) - Inspiration for the terminal implementation
- [xterm.js](https://xtermjs.org/) - Terminal emulator for the browser
- [Gradio](https://gradio.app/) - The awesome ML demo framework
