portless CLI
CLI от Vercel Labs: вместо localhost:3000 dev-сервер открывается по постоянному адресу https://myapp.localhost, у каждой ветки git свой
- 12 760 ★ репозитория
- Последний коммит
- Apache-2.0
Широкий доступ
Почему такой уровень
- Добавляет собственный корневой сертификат в хранилище доверия системы и занимает порт 443 с запросом sudo
- Меняет `/etc/hosts` и может установить службу с правами root, которая стартует при загрузке системы
- Ключи `--funnel` и `--ngrok` выставляют dev-сервер в интернет, а `--lan` открывает его всей локальной сети
Установка
В терминале, через SkillFoxx CLI
npx skillfoxx add cli/portlessОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Добавляет собственный корневой сертификат в хранилище доверия системы и занимает порт 443 с запросом sudo
- Меняет `/etc/hosts` и может установить службу с правами root, которая стартует при загрузке системы
- Ключи `--funnel` и `--ngrok` выставляют dev-сервер в интернет, а `--lan` открывает его всей локальной сети
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
portless заменяет номера портов локальной разработки именами. Команда `portless myapp next dev` запускает ваш dev-сервер и открывает его по адресу `https://myapp.localhost`. Для этого работает обратный прокси: при первом запуске он создает локальный сертификат, добавляет его в хранилище доверенных сертификатов системы и занимает порт 443 (на macOS и Linux для этого запрашивает sudo). Приложению portless назначает случайный порт из диапазона 4000–4999 через переменную `PORT`, а для Vite, Astro, Angular, Expo и других фреймворков, которые ее игнорируют, сам подставляет флаг `--port`. Голая команда `portless` запускает скрипт `dev` из `package.json` и берет имя из пакета, корня git или папки. В монорепозитории один `portless.json` в корне покрывает все пакеты, а имена вида `api.myapp` дают поддомены. В связанном рабочем дереве git имя ветки ставится перед адресом, поэтому у `fix-ui` будет `fix-ui.myapp.localhost` без правки конфига. Ключи `--tailscale`, `--funnel` и `--ngrok` открывают приложение для команды или в интернете, а `--lan` делает его доступным на устройствах сети как `myapp.local`. Агентам portless снимает путаницу с портами: адрес приложения всегда один и тот же. В репозитории лежат два скилла: `portless` с руководством по настройке и `oauth` для случаев, когда провайдер входа отклоняет адрес `.localhost`.
Для кого. Для веб-разработчиков с несколькими dev-серверами и монорепозиториями, а также для тех, чьи агенты часто промахиваются портом при тестировании приложения.
Подходит, если
- Несколько проектов одновременно просят порт 3000, и сервер падает с ошибкой `EADDRINUSE`
- Агент тестирует приложение и подставляет не тот порт: постоянный адрес убирает угадывание
- Вы работаете с git worktree, и нужен отдельный адрес на каждую ветку без правки конфигов
- Куки и localStorage разных проектов смешиваются на `localhost`, и их нужно развести по именам
- Надо показать dev-сервер коллеге по Tailscale или с телефона по Wi-Fi через `--lan`
Не подходит, если
- На компьютере Node.js ниже 24-й версии: portless требует Node.js 24 и новее
- Нельзя добавлять корневой сертификат в систему и занимать порт 443: по умолчанию portless так и поступает
- Нужна помощь агенту с самим кодом Next.js: отладку dev-режима в каталоге берет на себя Next.js DevTools MCP, а portless лишь называет сервер по имени
- Приложение работает в контейнере или на удаленной машине без доступа к вашему браузеру: прокси работает на локальных адресах `127.0.0.1` и `::1`
Пример запроса к агенту
Подключи portless к этому монорепозиторию, чтобы web и api открывались как myapp.localhost и api.myapp.localhost, и проверь результат через portless listОграничения
Проект до версии 1.0: автор предупреждает, что формат каталога состояния может меняться между релизами, и тогда придется заново выполнить `portless trust`. При установке в проект у участников команды могут оказаться разные версии, а значит, и разный формат состояния.
Требуются Node.js 24 или новее и macOS, Linux или Windows. Для `--tailscale` и `--funnel` нужен клиент Tailscale с включенными HTTPS-сертификатами, для `--ngrok` — клиент ngrok с токеном. Режим `--lan` на Linux опирается на `avahi-publish-address` из пакета `avahi-utils`, на macOS — на `dns-sd`.
В Safari поддомены `.localhost` на части конфигураций не открываются: portless по умолчанию синхронизирует блок в `/etc/hosts`, а отключить это можно переменной `PORTLESS_SYNC_HOSTS=0`. В среде без терминала или при `CI=1` portless не задает вопросов и завершается с ошибкой.
Фреймворки с проверкой источников, например Next.js в режиме LAN, требуют добавить имена `.local` в `allowedDevOrigins`. Google и Apple отвергают адреса `.localhost`, поэтому для OAuth нужен ключ `--tld` с доменом из списка публичных суффиксов.
Лицензия Apache-2.0.
Как отключить. Команда `portless clean` удаляет состояние в `~/.portless`, корневой сертификат из хранилища системы и блок в `/etc/hosts`, а `portless service uninstall` снимает автозапуск прокси. Потом удалите пакет через `npm uninstall -g portless`. Чтобы обойти прокси один раз, запустите команду с `PORTLESS=0`.
Частые вопросы
Зачем portless просит sudo?
Прокси по умолчанию занимает порт 443, а на macOS и Linux привилегированные порты требуют повышенных прав. Для адресов без привилегий есть порт 1355 и ключ `-p`. Кроме того, sudo нужен для добавления локального сертификата в хранилище системы.
Что делать, если Safari не открывает адрес .localhost?
Выполните `portless hosts sync`: команда сверит маршруты с `/etc/hosts`. Позже записи убираются командой `portless hosts clean`. Chrome, Firefox и Edge сами сводят поддомены `.localhost` к `127.0.0.1`.
Как работает portless с несколькими worktree?
В связанном рабочем дереве `portless run` ставит имя ветки поддоменом: основная копия остается `myapp.localhost`, а ветка `fix-ui` получает `fix-ui.myapp.localhost`. Ключ `--name` меняет базовое имя, префикс ветки остается.
Как открыть приложение с телефона?
Запустите прокси с `portless proxy start --lan`: он слушает `0.0.0.0`, объявляет имена через mDNS, и приложение доступно как `<имя>.local` на устройствах той же сети. Адрес сети определяется сам и следует за сменой Wi-Fi.
Как выставить сервер наружу?
`--tailscale` публикует приложение в вашей сети Tailscale, `--funnel` открывает его всему интернету через Tailscale Funnel, а `--ngrok` строит туннель ngrok. Туннель снимается, когда приложение завершается.
Что проверяет `portless doctor`?
Команда ничего не меняет и смотрит Node.js, каталог состояния, работу прокси, записи маршрутов, доверие к сертификату, разрешение имен и условия режима LAN, а затем печатает советы по исправлению.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыТуннель для localhost с собственным реле: публичный HTTPS-адрес для локального сервиса без аккаунта, плюс скиллы для агентов
Удаленный MCP-сервер платформы Devopness, которая создает инфраструктуру и выкладывает приложения в ваших облачных аккаунтах
Локальный шлюз перед git push: ревью, тесты, документация и линтер проходят в отдельной копии, и только после этого ветка уходит в удаленный репозиторий
3X-UI на своем VPS
3x-ui-vps
Скилл, который разворачивает панель 3X-UI и Xray VLESS за nginx на Ubuntu-сервере и затем обслуживает его через готовые скрипты
Container от Aerovato
Container
CLI для постоянных Linux-окружений в Docker или Podman: у каждого проекта свой контейнер, где агент не видит остальную систему
CLI, который одной командой публикует собранный фронтенд в IPFS, а также разворачивает небольшие фулстек-проекты; в комплекте скиллы для агентов
Коротко о README
В репозитории лежат пакет `packages/portless` на TypeScript с тестами, документация для сайта, примеры, журнал изменений и два скилла. Описание проекта разбирает установку, запуск приложения, конфигурацию в `portless.json` и в `package.json`, монорепозитории, Turborepo, поддомены, рабочие деревья git, свои домены верхнего уровня, HTTP/2, автозапуск службы, режим LAN, публикацию через Tailscale и ngrok, справочник команд и переменных, удаление и устранение неполадок.