lyehe/porterminalБыстрый и грязный веб/MCP туннель терминала для вашего телефона и ПК
<p align="center">
<a href="https://github.com/porterminal/porterminal">
<img src="https://raw.githubusercontent.com/porterminal/porterminal/master/assets/header.png?v=9" alt="PTN — Portable Terminal with decorative QR artwork." width="800">
</a>
</p>
<h1 align="center">Дайте своему агенту любой компьютер</h1>
<p align="center">
Одна команда. Один URL. Настоящий терминал для вашего агента, живой просмотр для вас.
</p>
<p align="center">
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/v/ptn?style=flat-square&logo=pypi&logoColor=white&label=PyPI" alt="PyPI"></a>
<a href="https://pypi.org/project/ptn/"><img src="https://img.shields.io/pypi/pyversions/ptn?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/porterminal/porterminal/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/porterminal/porterminal/ci.yml?branch=master&style=flat-square&logo=github&label=CI" alt="CI"></a>
<a href="https://github.com/porterminal/porterminal/blob/master/LICENSE"><img src="https://img.shields.io/github/license/porterminal/porterminal?style=flat-square" alt="License"></a>
</p>
Запустите Porterminal на компьютере с Windows, macOS или Linux и передайте
сгенерированную ссылку своему ИИ-агенту. Он получит настоящую оболочку с файлами, инструментами и проектами
на этой машине. Откройте ту же ссылку на телефоне или в любом браузере, чтобы наблюдать
за работой агента и вводить команды в его терминал.
## Начните здесь
На компьютере, который вы хотите предоставить своему агенту:
```bash
uvx ptn
```
1. **Передайте агенту ссылку.** Нажмите **`c`** в локальном окне Porterminal,
чтобы скопировать URL и инструкции по подключению. Вставьте их в своего агента
вместе с задачей. Агенту нужна поддержка удалённого MCP или способ выполнять HTTP-запросы.
2. **Откройте свой вид.** Отсканируйте QR-код или откройте полный URL в браузере.
Выберите **вкладку 🤖** агента, чтобы увидеть его терминал.
3. **Работайте вместе.** Наблюдайте за выводом, отвечайте на интерактивный запрос, вводите
команду или закройте вкладку, чтобы завершить эту оболочку.
4. **Получайте доступ к своему компьютеру с любого телефона.** Используйте браузер телефона для
вайб-кодинга, быстрых исправлений, запуска команд и многого другого.
Чтобы начать в конкретном проекте, используйте `uvx ptn /path/to/project`.
Варианты установки см. в разделе [installation](https://github.com/porterminal/porterminal/blob/master/docs/installation.md) или воспользуйтесь установщиком ниже.
> **Ссылка — это ключ к компьютеру.** Полный URL и QR-код предоставляют
> доступ к оболочке. Делитесь ими только с теми людьми и агентами, которым доверяете.
> [Прочитать модель безопасности](#security).
## Агент работает. Вы остаётесь в курсе.
| Ваш агент | Вы |
|------------|-----|
| Выполняет команды в реальной оболочке компьютера | Наблюдаете за тем же выводом в реальном времени в браузере |
| Читает экраны терминала и отвечает на запросы | Вводите текст в тот же терминал при необходимости |
| Сохраняет состояние оболочки между вызовами инструментов | Переключаетесь между вкладками агента и личными вкладками |
| Использует MCP или HTTP для подключения | Используете QR-код или URL с телефона или компьютера |
Ввод в терминал общий; согласовывайте ввод текста с вашим агентом. Porterminal
поддерживает интерактивные терминальные приложения, несколько вкладок и переподключение к работающим
сессиям, пока сервер и сессия остаются активными.
Мобильный интерфейс включает клавиши Ctrl/Alt/Shift, выделение касанием, прокрутку,
масштабирование жестом и поле ввода для редактирования или диктовки более длинного текста.
См. [terminal controls](https://github.com/porterminal/porterminal/blob/master/docs/frontend_features.md).
## Попробуйте демо
Дайте агенту небольшой проект счёта-фактуры с падающей проверкой. Наблюдайте, как он находит
ошибку, редактирует файл и делает проверки зелёными. Затем ответьте на запрос метки в квитанции
со своего телефона и попросите агента прочитать результат.
[Руководство по демо](https://github.com/porterminal/porterminal/blob/master/docs/demo.md) включает готовый к копированию проект, задачу для агента
и план 60-секундной записи. Оно демонстрирует команды, изменения файлов,
проверку и ввод человеком в одной общей сессии.
## Подключите своего агента
Нажатие **`c`** копирует инструкции для доступных способов подключения.
Работающий сервер также отдаёт их по адресу `<url>/llms.txt`.
Здесь **`<url>` — это полный сгенерированный URL, включая его код доступа**.
| Возможность агента | Подключение |
|------------------|------------|
| Удалённый MCP | `<url>/mcp` — Streamable HTTP |
| HTTP-запросы | `<url>/api/agent/run` — REST |
| Автоматизация браузера | Откройте `<url>/`; используйте **Terminal screen** и **Terminal input** |
MCP предоставляет четыре инструмента: `run_command`, `read_screen`, `send_keys` и
`send_signal`. REST возвращает `session_id`, который агент повторно использует для последующих
команд и взаимодействия. Оболочки агента отображаются как вкладки 🤖 в вашем браузере.
См. [agent access](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md) для настройки клиента, примеров запросов,
времени жизни сессий и длительных команд.
## Установка
Требуется **Python 3.12+**. Porterminal пытается установить `cloudflared`
автоматически, если он отсутствует.
| Способ | Запуск или установка | Обновление |
|--------|----------------|--------|
| uvx | `uvx ptn` | `uvx --isolated ptn@latest` |
| uv tool | `uv tool install ptn` | `uv tool upgrade ptn` |
| pipx | `pipx install ptn` | `pipx upgrade ptn` |
| pip | `pip install ptn` | `pip install -U ptn` |
**Установите uv и Porterminal вместе:**
Windows (PowerShell):
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/porterminal/porterminal/master/install.ps1 | iex"
```
macOS / Linux:
```bash
curl -LsSf https://raw.githubusercontent.com/porterminal/porterminal/master/install.sh | sh
```
## Использование
После установки запустите `ptn` или `ptn /path/to/project`.
| Опция | Назначение |
|--------|---------|
| `--no-tunnel` | Запуск без туннеля Cloudflare |
| `--mcp-only` | Открывает только MCP; отключает QR-код, браузерный терминал и REST API |
| `--compose` | Запуск с включённым полем мобильного compose |
| `--init` | Создаёт `.ptn/ptn.yaml` с кнопками, обнаруженными из скриптов проекта |
| `--password` | Добавляет пароль для доступа к браузерному терминалу |
| `--help` | Показывает все опции |
| `--version` | Показывает установленную версию |
Во время работы: **`c`** копирует инструкции для агента, **`u`** копирует только
URL, а **`s`** показывает текст для отправки на экране (**`q`** закрывает его).
**Ctrl+C** останавливает Porterminal. В режиме только MCP клавиши отправки используют URL MCP.
Пользовательские оболочки, кнопки панели инструментов и настройки запуска находятся в `ptn.yaml`.
См. [конфигурацию](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md).
## Безопасность
Porterminal предоставляет доступ к реальной оболочке с правами вашего пользователя. Стартовый
каталог — это удобство, а не песочница и не ограничение доступа к файлам.
Каждый запуск создаёт новый случайный путь доступа длиной 128 бит. Голое имя хоста туннеля
и неверные пути возвращают 404, но любой, у кого есть полный URL, может использовать оболочку.
Держите URL и QR-код в тайне, останавливайте Porterminal по завершении работы и перезапускайте
его, чтобы сменить код доступа, если ссылка утекла.
**Необязательный пароль защищает подключения из браузера. MCP и REST используют
полный URL в качестве учётных данных и не требуют этого пароля.**
Полную модель и поведение пароля см. в разделе [безопасность](https://github.com/porterminal/porterminal/blob/master/docs/security.md).
Сообщайте об уязвимостях через [политику безопасности](https://github.com/porterminal/porterminal/blob/master/.github/SECURITY.md).
## Документация и разработка
- [Установка](https://github.com/porterminal/porterminal/blob/master/docs/installation.md)
- [Доступ агента: MCP, REST и браузерный резервный вариант](https://github.com/porterminal/porterminal/blob/master/docs/agent-access.md)
- [Настройка демо и запись](https://github.com/porterminal/porterminal/blob/master/docs/demo.md)
- [Конфигурация](https://github.com/porterminal/porterminal/blob/master/docs/configuration.md)
- [Архитектура](https://github.com/porterminal/porterminal/blob/master/docs/architecture.md)
- [Разработка и процесс выпуска](https://github.com/porterminal/porterminal/blob/master/docs/development.md)
- [Журнал изменений](https://github.com/porterminal/porterminal/blob/master/docs/CHANGELOG.md)
Отчёты об ошибках и запросы функций приветствуются в виде
[issues](https://github.com/porterminal/porterminal/issues).
Внешние pull-запросы и вклады в код не принимаются; см.
[CONTRIBUTING.md](https://github.com/porterminal/porterminal/blob/master/CONTRIBUTING.md). Вы можете сделать форк и запускать собственную копию.
## Лицензия
[AGPL-3.0](https://github.com/porterminal/porterminal/blob/master/LICENSE)