porterminal v1.0.5

Дайте агенту компьютер, полный контроль и наблюдайте.
Одна команда, один URL. (А ещё — отличный терминал для вашего телефона.)

1. uvx ptn
2. Отдайте URL ИИ-агенту или отсканируйте QR-код сами
3. Наблюдайте за работой в любом браузере и в любой момент берите управление на себя

[!WARNING] Этот URL даёт полный доступ к вашему компьютеру. Любой человек (или ИИ-агент), которому вы его передадите, получит реальную командную оболочку на вашей машине без пароля. В этом и заключается суть, но чрезвычайно легко предоставить агенту больше, чем вы собирались. Относитесь к URL как к секрету, передавайте его только доверенным людям и агентам и прочитайте раздел Безопасность, прежде чем использовать его для чего-то важного.

Зачем

Мне нужно было что-то, что позволяет опасно легко получить удалённый доступ к компьютеру.

ngrok требует регистрации, а бесплатный тариф никуда не годится. Cloudflare Tunnel — отличная технология, но сам по себе он даёт только туннель, а не удобный для телефона терминал. Tailscale хорош, когда вы владеете обоими концами, но всё равно требует подключения устройств к частной сети. Termius требует сложной настройки: проброс портов, правила брандмауэра, управление ключами...

Поэтому я создал нечто более простое: выполните команду, отсканируйте QR, начинайте печатать.

Затем я понял: тот же трюк (одна команда, один URL) — это самый простой способ дать ИИ-агенту реальный терминал на любом компьютере. Никакого MCP-сервера, никаких SSH-ключей, никакого Docker, никакой конфигурации. Запустите uvx ptn, передайте URL, и агент будет выполнять команды, читать экран и отвечать на подсказки на этой машине. А поскольку это веб-терминал, вы можете открыть ту же сессию в любом браузере, чтобы наблюдать за работой в реальном времени или перехватить клавиатуру и взять управление на себя.

Возможности

• Дайте агенту компьютер, полный контроль и наблюдайте — Передайте агенту URL, и он получит реальный терминал на машине через MCP или обычный REST. Откройте ту же сессию в любом браузере, чтобы видеть его работу вживую, и в любой момент берите клавиатуру в свои руки. Никаких ключей, никакого Docker. Агент узнаёт, как работать, из /llms.txt и /.well-known/mcp.json. См. Доступ агентов.
• Одна команда, мгновенный доступ — uvx ptn — и вы (или агент) получаете реальный терминал на этой машине. Никакого SSH, проброса портов, конфигурационных файлов. Cloudflare-туннель + QR-код.
• Реально работает на мобильных устройствах — Оптимизирован для сенсорного управления: инерционная прокрутка, масштабирование pinch-to-zoom, жесты свайпа и клавиши-модификаторы (Ctrl, Alt).
• Полноценные терминальные приложения — vim, htop, less, tmux работают корректно с правильной обработкой альтернативного буфера экрана.
• Постоянные сессии с несколькими вкладками — Сессии переживают разрывы соединения. Закройте браузер, смените сеть, переподключитесь с другого устройства — ваша оболочка и запущенные процессы останутся на месте. Вы и агент можете использовать одну сессию: наблюдайте за работой или берите управление.
• Кроссплатформенность — Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish, Nushell и любая оболочка через $SHELL). Автоматически определяет ваши оболочки.
• Приватность по умолчанию — Секретный URL туннеля никогда не отображается на экране, так что можно безопасно демонстрировать экран или снимать QR-код. Нажмите c, чтобы скопировать инструкции для агента и URL, или u, чтобы скопировать только URL.

Установка

Одноразовая установка (uv + ptn):

Требуется Python 3.12+ и cloudflared (устанавливается автоматически, если отсутствует).

Использование

ptn                    # Запуск в текущей директории
ptn ~/projects/myapp   # Запуск в указанной папке

Во время работы: если активен туннель, URL подключения скрыт с экрана для приватности. Нажмите c, чтобы скопировать инструкции для агента и URL (включая /mcp, /api/agent/run и /llms.txt); нажмите u, чтобы скопировать только URL; или отсканируйте QR для подключения. Ctrl+C останавливает сервер.

Доступ агентов (MCP + REST)

Тот же URL работает и для ИИ-агентов. Клиенты, поддерживающие MCP, могут использовать <url>/mcp (Streamable HTTP) для нативных типизированных инструментов. Агенты, которые не могут зарегистрировать MCP-сервер, могут использовать REST-запасной вариант по адресу <url>/api/agent/run с обычными HTTP-запросами. Любой из этих путей создаёт постоянную оболочку агента, которая отображается как вкладка 🤖 — вы можете наблюдать за ней и перехватывать управление с телефона.

Передайте агенту URL туннеля. MCP-клиенты могут автоматически обнаружить сервер через <url>/.well-known/mcp.json (дескриптор MCP server.json). Также доступен <url>/llms.txt для человека и агента с инструкциями по использованию. Базовая страница также содержит подсказки для агентов, управляющих браузером (через доступность), а интерфейс для человека остаётся компактным. Пример конфигурации клиента:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/mcp" }
  }
}

MCP-инструменты: run_command (чистый вывод + код возврата), read_screen, send_keys, send_signal (Ctrl-C / EOF).

REST-запасной вариант:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

Ответ содержит session_id; используйте его с /api/agent/screen, /api/agent/keys, /api/agent/signal и DELETE /api/agent/session.

Когда вы открываете Porterminal на телефоне, кнопка копирования в правом верхнем углу копирует тот же текст для передачи агенту. Для агентов, работающих только через браузер, также предусмотрен запасной вариант на базовой странице: DOM-читаемое зеркало Terminal screen и чётко обозначенный ввод Terminal input.

Безопасность: как и для человеческого терминала, единственная защита — это секретный URL туннеля. Любой (или любой агент), кто его получит, получит полный непривилегированный доступ к оболочке. Если вам нужна настоящая аутентификация, используйте другой инструмент. См. docs/agent-access.md.

Жесты на мобильных устройствах

Клавиши-модификаторы (Ctrl, Alt, Shift): одно касание для однократного использования (один нажатие), двойное касание для фиксации.

Режим compose (кнопка ▤): включает поле ввода текста, где можно печатать или диктовать, редактировать текст со всеми возможностями мобильного ввода (автозамена, подсказки, позиционирование курсора), затем отправить в терминал. Полезно для длинных команд или голосового ввода.

Конфигурация

Запустите ptn --init, чтобы создать стартовый конфиг. Он автоматически находит скрипты проекта из package.json, pyproject.toml или Makefile и добавляет их как кнопки:

ptn -i
# Создан: .ptn/ptn.yaml
# Обнаружено 3 скрипта проекта: build, dev, test

Или создайте ptn.yaml вручную:

# Настройки терминала
terminal:
  default_shell: nu              # ID оболочки по умолчанию
  shells:                        # Пользовательские определения оболочек
    - id: nu
      name: Nushell
      command: nu
      args: []

# Пользовательские кнопки (отображаются на панели инструментов)
# row: 1 = строка по умолчанию, 2+ = дополнительные строки
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # задержка в мс
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # вторая строка кнопок

# Настройки проверки обновлений
update:
  notify_on_startup: true   # Показывать уведомление об обновлении
  check_interval: 86400     # Интервал проверки в секундах (по умолч. 24ч)

# Настройки безопасности
security:
  require_password: true    # Всегда запрашивать пароль при запуске
  password_hash: ""         # Сохранённый хеш пароля (используйте ptn -sp для установки)
  max_auth_attempts: 5      # Максимум неудачных попыток до разрыва соединения

Конфиг ищется в следующем порядке: $PORTERMINAL_CONFIG_PATH, ./ptn.yaml, ./.ptn/ptn.yaml, ~/.ptn/ptn.yaml.

Безопасность

По умолчанию пароля нет. Единственное, что мешает несанкционированному доступу — то, что никто не угадает случайный URL туннеля. Любой (или любой ИИ-агент), кто его получит, имеет полный доступ к вашей оболочке. Не доверяйте ему ничего, что вы не дали бы незнакомцу, и установите пароль для всего важного:

Из интерфейса: Откройте Настройки (значок шестерёнки) и используйте раздел Безопасность, чтобы установить/изменить пароль и включить/выключить обязательный пароль. Изменения требуют перезапуска сервера.

Из командной строки:

# Одноразовый пароль (запрашивается при каждой сессии)
ptn -p

# Сохранить пароль в конфиг (без запроса при запуске)
ptn -sp
# Пароль: ****
# Подтвердите пароль: ****

# Очистить сохранённый пароль (введите пустой пароль)
ptn -sp
# Пароль: [нажмите Enter]

# Включить/выключить обязательный пароль
ptn -tp on       # Включить
ptn -tp off      # Выключить
ptn -tp toggle   # Переключить текущее состояние

См. docs/security.md для подробностей.

Устранение неполадок

Не удаётся подключиться? Cloudflare-туннель иногда блокирует соединения. Перезапустите сервер (Ctrl+C, затем ptn), чтобы получить новый URL туннеля.

Оболочка не обнаружена? Установите переменную окружения $SHELL или настройте оболочки в ptn.yaml.

Участие в разработке

Этот проект не принимает внешние вклады (пул-реквесты или изменения в коде) по соображениям безопасности (см. CONTRIBUTING.md). Вы можете форкнуть проект и запустить свою копию в соответствии с AGPL-3.0.

Запуск из исходников:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

Лицензия

AGPL-3.0