Tunnelhunt Skills: как научить AI-агентов управлять туннелями через npx skills

В эру Vibe Coding и автономных кодинг-агентов (таких как Claude Code, Cursor Composer, Windsurf, Cline, Codex) разработка перешла на новый уровень. Вы формулируете задачу на естественном языке, а агент сам пишет код, создает структуру проекта, ставит зависимости и запускает локальный dev-сервер.

Но в тот самый момент, когда приложению требуется взаимодействие с внешним миром — принять вебхук от Telegram Bot API, обработать платеж от Stripe / Т-Банка / ЮKassa, подтвердить авторизацию по OAuth или просто показать результат верстки на реальном смартфоне — агент упирается в непреодолимую стену:

Внешний интернет не имеет доступа к вашему http://localhost:3000.

Традиционные решения вроде ngrok или cloudflared создают в агентных пайплайнах массу проблем: агенты пытаются установить сторонние бинарники, застревают на требованиях регистрации и проброса токенов в env, а при сбоях бросают задачу и требуют ручного вмешательства человека.

Чтобы решить эту проблему раз и навсегда, мы выпустили официальный Agent Skill для Tunnelhunt с открытым репозиторием github.com/tunnelhunt/skills и поддержкой менеджера skills.sh.

Что такое Agent Skills и зачем они нужны?

Спецификация Agent Skills (разработанная сообществом и стандартизированная платформой skills.sh) — это открытый формат расширения возможностей AI-агентов.

Скилл представляет собой структурированную базу знаний с метаданными (SKILL.md), которая:

1. Активируется автоматически: нейросеть понимает, в каких ситуациях (по ключевым симптомам и запросам пользователя) нужно задействовать этот навык.
2. Дает четкие алгоритмы: агент получает строгие инструкции, как запускать фоновые процессы, какие аргументы передавать, как перехватывать ошибки и как правильно форматировать ссылки для пользователя.
3. Исключает галлюцинации: агент перестает изобретать неработающие скрипты или советовать пользователю сторонние платные сервисы.

Установка в 1 клик через npx skills

Менеджер пакетов навыков skills позволяет добавить Tunnelhunt в вашу среду разработки буквально за несколько секунд.

1. Установка в проект

Если вы хотите, чтобы все разработчики и агенты в конкретном репозитории имели доступ к скиллу:

npx skills add tunnelhunt/skills

2. Глобальная установка (Рекомендуется)

Чтобы навык был доступен вашим ассистентам во всех проектах на компьютере:

npx skills add tunnelhunt/skills -g

3. Установка для конкретных ассистентов

Менеджер автоматически определяет поддерживаемые среды, но при желании вы можете указать целевых агентов явно:

# Для Claude Code и Cursor:
npx skills add tunnelhunt/skills --agent claude-code cursor

# Для всех поддерживаемых агентов сразу (включая Windsurf и Cline):
npx skills add tunnelhunt/skills --agent '*' -y

4. Установка по прямой ссылке

npx skills add https://github.com/tunnelhunt/skills.git

После установки в директории навыков агента появится папка tunnelhunt с инструкциями, рецептами и вспомогательными скриптами.

Главная суперсила: Zero-Install через OpenSSH

Большинство инструментов туннелирования требуют установки своего проприетарного CLI-клиента. Для человека это пара команд, но для автономного AI-агента это источник частых ошибок:

• В изолированной песочнице агента может не быть прав sudo.
• Менеджеры пакетов (brew, apt) могут быть недоступны или работать в readonly-окружении.
• Требуется открывать браузер, заводить аккаунт, копировать authtoken.

Tunnelhunt устроен иначе. Он работает поверх стандартного протокола SSH, который гарантированно предустановлен на macOS, дистрибутивах Linux и в Windows 10/11.

Скилл обучает агента безопасному запуску туннеля через одну команду:

ssh -p 2222 -R 80:localhost:3000 \
  -o StrictHostKeyChecking=no \
  -o UserKnownHostsFile=/dev/null \
  -o ServerAliveInterval=30 \
  -N tunnelhunt.ru

Что делает агент под капотом:

1. Запускает SSH в фоновом режиме с флагом -N (только проброс портов) и защитой от зависания (ServerAliveInterval=30).
2. Сохраняет PID процесса в файл (например, /tmp/tunnelhunt_3000.pid), чтобы гарантированно закрыть туннель после завершения работы.
3. Перехватывает выделенный HTTPS-адрес (https://<subdomain>.tunnelhunt.ru).
4. Предоставляет пользователю готовую кликабельную ссылку в чате.

Два режима работы: SSH и MCP

Скилл Tunnelhunt гибок и поддерживает оба современных подхода к архитектуре агентов:

                  Запрос на проброс порта
                             │
            ┌────────────────┴────────────────┐
            ▼                                 ▼
   Режим 1: Native SSH               Режим 2: MCP Server
 (Claude Code, Terminal)            (Cursor, Cline, Windsurf)
            │                                 │
     Стандартный OpenSSH              Инструменты MCP:
   без установки бинарников          - start_tunnel
                                     - get_tunnel_logs
                                     - stop_tunnel

Если в клиенте (например, Cursor или Claude Desktop) настроен сервер @tunnelhunt/mcp, агент будет предпочитать нативные вызовы инструментов через Model Context Protocol. Если же агент работает в терминале (как Claude Code), он воспользуется нативным SSH.

Реальные сценарии использования

Сценарий 1: Разработка Telegram-бота с Webhook

Раньше для локального тестирования ботов приходилось использовать long polling (что медленно и не отражает реальный прод) либо вручную запускать сторонние утилиты.

Теперь вы просто пишете агенту:

«Напиши Telegram-бота на Python с помощью aiogram, подними локальный сервер на FastAPI и настрой вебхук через tunnelhunt».

Что делает агент:

1. Пишет код бота с обработчиком /start и эндпоинтом /webhook.
2. Запускает локальный сервер на порту 8000.
3. Открывает туннель через Tunnelhunt и получает https://silver-fox.tunnelhunt.ru.
4. Делает запрос к Telegram API:

   curl -s -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -d '{"url": "https://silver-fox.tunnelhunt.ru/webhook"}'

5. Проверяет статус через getWebhookInfo и сообщает вам: «Бот запущен, вебхук зарегистрирован на https://silver-fox.tunnelhunt.ru/webhook, отправьте боту сообщение в Telegram!».

Сценарий 2: Отладка платежных вебхуков (Stripe / Т-Банк / ЮKassa)

Платежные шлюзы отправляют уведомления об успешной оплате асинхронно через HTTP POST.

С установленным скиллом агент:

1. Запускает обработчик маршрута /api/payments/webhook.
2. Пробрасывает туннель с постоянным или временным субдоменом.
3. Читает входящие логи (через get_tunnel_logs или SSH-журнал) и моментально видит, какой payload пришел от банка, совпала ли подпись и вернул ли ваш код HTTP 200 OK.

Сценарий 3: Демонстрация верстки и мобильное тестирование

Когда агент сверстал адаптивный интерфейс на Next.js или Vite, разработчику часто нужно открыть страницу с физического смартфона или отправить ссылку коллеге в Slack/Telegram:

«Пробрось мое приложение на порту 5173 в интернет, чтобы я открыл его на телефоне».

Агент выполняет:

./skills/tunnelhunt/scripts/tunnel.sh start 5173

И выдает красивую ссылку https://swift-falcon.tunnelhunt.ru, доступную отовсюду без необходимости находиться в одной Wi-Fi сети.

Архитектура репозитория tunnelhunt/skills

Репозиторий оформлен в соответствии с лучшими стандартами модульной архитектуры навыков (Tier 2 Architecture):

• SKILL.md — компактный и емкий файл инструкций с точными триггерами и правилами поведения.
• references/ssh-reference.md — справочник по SSH-параметрам, флагам демонизации и авторизации по SSH-ключам.
• references/mcp-server.md — руководство по подключению пакета @tunnelhunt/mcp в конфигурациях клиентов.
• references/webhooks.md — готовые пошаговые рецепты для Telegram, Stripe, GitHub, Discord и OAuth 2.0.
• references/troubleshooting.md — автодиагностика сетевых ошибок, конфликтов портов и обрывов связи.
• scripts/tunnel.sh — переносимый bash-скрипт с командами start, stop, status и logs.

Заключение

Инструменты туннелирования для людей и инструменты для AI-агентов должны быть устроены по-разному. Агентам не нужны тяжелые GUI-клиенты и запутанные формы авторизации — им нужны надежность, нативные протоколы и нулевая стоимость интеграции.

Tunnelhunt Skills превращает ваш локальный терминал и любимого AI-агента в единый слаженный механизм для Vibe Coding.

👉 Попробуйте прямо сейчас:

npx skills add tunnelhunt/skills -g

Исходный код открыт на GitHub: github.com/tunnelhunt/skills. Будем рады звездам и вашим pull request’ам!