porterminal v1.2.0

Передайте компьютер агенту, полный контроль, и наблюдайте за ним.
Одна команда, один URL. (А также удобный терминал для вашего собственного телефона.)

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

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

Зачем

Мне нужно что-то опасно простое для удалённого доступа к компьютеру.

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

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

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

Возможности

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

Установка

Установка одной строкой (uv + ptn):

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

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

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

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

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

Для управления оболочкой полностью за кулисами запустите ptn --mcp-only. Локальный терминальный интерфейс остаётся открытым: нажмите c, чтобы скопировать приглашение для агента и адрес MCP, или u, чтобы скопировать только адрес MCP. Эти клавиши также работают с --no-tunnel. Подключите ваш MCP-клиент к сгенерированной конечной точке <url>/mcp. В этом режиме не показывается QR-код и отключаются веб-терминал, браузерные WebSockets и REST API, поэтому команды нельзя наблюдать или вводить через браузер. Обнаружение MCP и /llms.txt остаются доступными. Полный URL MCP по-прежнему предоставляет управление оболочкой компьютера.

Тот же 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/<access-code>/mcp" }
  }
}

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

REST-резерв:

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

Ответ включает session_id; используйте его повторно с <url>/api/agent/screen, <url>/api/agent/keys, <url>/api/agent/signal и DELETE <url>/api/agent/session.

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

Безопасность: <url> означает полный сгенерированный URL, включая его случайный код доступа. Голое имя хоста туннеля ничего не раскрывает, но любой (или любой агент) с полным URL получает полный доступ к оболочке без повышения привилегий. См. docs/agent-access.md.

Мобильные жесты

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

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

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

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

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

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

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

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

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

Каждый запуск создаёт новый случайный путь длиной 128 бит, например https://<tunnel>.trycloudflare.com/<access-code>/. Все маршруты браузера, WebSocket, MCP, REST, проверки работоспособности и статики требуют именно этого префикса; голый хост и неверные пути возвращают 404. Это делает перебор обнаруженного имени хоста туннеля непрактичным.

Полный сгенерированный URL всё равно является предъявительским учётным данным: любой, кто его получит, имеет доступ к оболочке. Перезапустите Porterminal, чтобы сменить код, если он утечёт. Необязательный пароль добавляет аутентификацию для браузерных WebSockets, но MCP и REST продолжают доверять полному URL, чтобы агенты могли использовать рабочий процесс с одной ссылкой.

Браузер запоминает успешный пароль в хранилище в открытом виде, привязанном к этому полному URL запуска. Сохранение пароля для более нового запуска на том же источнике вытесняет более старые записи паролей Porterminal; очистка или отклонение запомненного пароля удаляет их все, не затрагивая другое хранилище браузера. Следовательно, параллельные запуски на одном источнике могут снова запросить пароль, тогда как уже аутентифицированное соединение остаётся подключённым.

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

Из CLI:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

Подробности см. в docs/security.md.

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

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

uvx ptn всё ещё запускает старую версию? Существующая установка uv tool может иметь приоритет. Запустите uv tool upgrade ptn или обойдите установленные инструменты с помощью uvx --isolated ptn@latest.

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

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

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

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

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

Лицензия

AGPL-3.0