Metadata-Version: 2.4
Name: gradio-terminal
Version: 1.1.1
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
with demo:
    terminal = Terminal(allow_sudo=False)  # Block sudo commands
```

### Terminal with Blacklist

```python
with demo:
    terminal = Terminal(
        blacklist_commands=["rm", "shutdown", "reboot"]  # Block dangerous commands
    )
```

## API Reference

| Function | Parameters | Description |
|----------|------------|-------------|
| `launch_terminal()` | `port=5000`, `host="127.0.0.1"`, `command="bash"`, `share=False`, `allow_sudo=True`, `blacklist_commands=None`, `**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`, `blacklist_commands=None` | 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`, `blacklist_commands=None` | 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.
- `blacklist_commands`: List of commands to block (default: None). Any command in this list will be blocked with an error message.

## Security

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

```python
terminal = Terminal(
    allow_sudo=False,
    blacklist_commands=["rm", "shutdown", "reboot", "passwd"]
)
```

## Disclaimer and Security Notice

This component provides shell access to your server, which can pose significant security risks if misused. It should only be used in trusted environments. While this package provides settings such as `allow_sudo=False` and `blacklist_commands` to reduce potential threats, it does not guarantee complete security. The authors are not responsible for any misuse or damage caused by this component.

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