Справочник

Поиск проблем и FAQ

Типичные проблемы, быстрые ответы и наиболее часто возникающие вопросы.

Если что-то здесь не совпадает с тем, что вы видите, пожалуйста, откройте issue, приложив платформу, браузер и соответствующий лог-файл из ~/.purplemux/logs/.

Установка и старт

tmux: command not found

purplemux требует tmux 3.0+ на хосте. Установите:

# macOS (Homebrew)
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Fedora
sudo dnf install tmux

Проверьте через tmux -V. tmux 2.9+ формально проходит preflight, но мы тестируем на 3.0+.

node: command not found или «Node.js 20 or newer»

Установите Node 20 LTS или новее. Проверьте через node -v. Нативное macOS-приложение содержит свой Node, поэтому это касается только путей npx / npm install -g.

"purplemux is already running (pid=…, port=…)"

Уже работает другой экземпляр purplemux и отвечает на /api/health. Используйте его (откройте напечатанный URL) или сначала остановите:

# найти его
ps aux | grep purplemux

# или просто убить через lock-файл
kill $(jq -r .pid ~/.purplemux/pmux.lock)

Устаревший lock — отказывается стартовать, но процесса нет

~/.purplemux/pmux.lock остался. Удалите:

rm ~/.purplemux/pmux.lock

Если когда-то запускали purplemux под sudo, файл может принадлежать root — один раз удалите его через sudo rm.

Port 8022 is in use, finding an available port...

Другой процесс владеет 8022. Сервер откатывается на случайный свободный порт и печатает новый URL. Чтобы выбрать порт самому:

PORT=9000 purplemux

Узнать, кто держит 8022: lsof -iTCP:8022 -sTCP:LISTEN -n -P.

Работает ли на Windows?

Не официально. purplemux опирается на node-pty и tmux, ни один из них не работает нативно на Windows. WSL2 обычно работает (вы фактически на Linux), но вне нашей матрицы тестов.

Сессии и восстановление

Закрытие браузера всё убило

Так быть не должно — tmux держит каждый шелл открытым на сервере. Если обновление страницы не возвращает вкладки:

  1. Проверьте, что сервер ещё работает (http://localhost:8022/api/health).
  2. Проверьте, что tmux-сессии существуют: tmux -L purple ls.
  3. Посмотрите ~/.purplemux/logs/purplemux.YYYY-MM-DD.N.log на ошибки в autoResumeOnStartup.

Если tmux говорит «no server running», хост перезагружался или что-то убило tmux. Сессии пропали, но раскладка (рабочие пространства, вкладки, рабочие каталоги) сохранена в ~/.purplemux/workspaces/{wsId}/layout.json и пересоздастся при следующем старте purplemux.

Сессия Claude не возобновляется

autoResumeOnStartup пере-выполняет сохранённый claude --resume <uuid> для каждой вкладки, но если соответствующего ~/.claude/projects/.../sessionId.jsonl уже нет (удалён, заархивирован или проект переехал), resume не сработает. Откройте вкладку и начните новый разговор.

Все мои вкладки показывают «unknown»

unknown означает, что вкладка была busy до перезапуска сервера и восстановление ещё идёт. resolveUnknown работает в фоне и подтверждает idle (Claude вышел) или ready-for-review (есть финальное сообщение ассистента). Если вкладка застряла в unknown дольше десяти минут, busy stuck safety net тихо переводит её в idle. Полную машину состояний см. в STATUS.md.

Браузер и UI

Web Push никогда не приходит

Пройдитесь по чек-листу:

  1. Только iOS Safari ≥ 16.4. В более ранних iOS Web Push нет вообще.
  2. На iOS обязательно PWA. Нажмите Поделиться → На экран «Домой» сначала; пуш не сработает из обычной вкладки Safari.
  3. HTTPS обязателен. Самоподписанные сертификаты не работают — Web Push молча отказывает в регистрации. Используйте Tailscale Serve (бесплатный Let's Encrypt) или настоящий домен за Nginx / Caddy.
  4. Разрешение на уведомления выдано. Настройки → Уведомления → Вкл в purplemux и разрешение на уровне браузера должны быть выданы оба.
  5. Подписки существуют. В ~/.purplemux/push-subscriptions.json должна быть запись для устройства. Если пусто, выдайте разрешение заново.

Полная матрица совместимости — в Поддержке браузеров.

iOS Safari 16.4+, но всё равно нет уведомлений

Некоторые версии iOS теряют подписку после долгого периода с закрытым PWA. Откройте PWA, отзовите и заново выдайте разрешение на уведомления, проверьте push-subscriptions.json.

Приватное окно Safari ничего не сохраняет

В приватных окнах Safari 17+ IndexedDB отключён, поэтому кеш рабочего пространства не переживает перезапуск. Используйте обычное окно.

Мобильный терминал исчезает после ухода в фон

iOS Safari закрывает WebSocket примерно через 30 с в фоне. tmux держит саму сессию живой — когда вы возвращаетесь во вкладку, purplemux переподключается и перерендеривает. Это iOS, не мы.

Firefox + Tailscale serve = предупреждение о сертификате

Если ваш tailnet использует кастомный домен не из *.ts.net, Firefox строже Chrome относится к доверию HTTPS. Один раз примите сертификат, и он запомнится.

«Браузер слишком старый» или нет каких-то функций

Запустите Настройки → Проверка браузера для отчёта по каждому API. Всё ниже минимумов в Поддержке браузеров теряет функции мягко, но не поддерживается.

Сеть и удалённый доступ

Можно ли выставить purplemux в интернет?

Можно, но всегда по HTTPS. Рекомендуемое:

  1. Tailscale Serve — tailscale serve --bg 8022 даёт WireGuard-шифрование и автоматические сертификаты. Проброс портов не нужен.
  2. Reverse-proxy — Nginx / Caddy / Traefik. Не забудьте пробросить заголовки Upgrade и Connection, иначе WebSocket'ы сломаются.

Обычный HTTP в открытом интернете — плохая идея: cookie аутентификации подписан HMAC, но нагрузки WebSocket (байты терминала!) не зашифрованы.

Другие устройства в LAN не могут достучаться до purplemux

По умолчанию purplemux разрешает только localhost. Откройте доступ через env или внутри приложения:

HOST=lan,localhost purplemux       # дружественно к LAN
HOST=tailscale,localhost purplemux # дружественно к tailnet
HOST=all purplemux                 # везде

Или Настройки → Сетевой доступ в приложении, что пишет в ~/.purplemux/config.json. (Когда HOST задан через env, поле заблокировано.) Синтаксис ключевых слов и CIDR — в Портах и переменных окружения.

Проблемы с WebSocket в reverse-proxy

Если /api/terminal подключается, а потом сразу падает, прокси срезает заголовки Upgrade / Connection. Минимальный Nginx:

location / {
  proxy_pass http://127.0.0.1:8022;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
}

Caddy: проброс WebSocket — это поведение по умолчанию; достаточно reverse_proxy 127.0.0.1:8022.

Данные и хранилище

Где мои данные?

Всё локально в ~/.purplemux/. С машины ничего не уходит. Пароль для логина — это scrypt-хеш в config.json. Полная раскладка — в Каталоге данных.

Я забыл пароль

Удалите ~/.purplemux/config.json и перезапустите. Онбординг начнётся заново. Рабочие пространства, раскладки и история сохраняются (это отдельные файлы).

Индикатор вкладки навсегда застрял на «busy»

busy stuck safety net тихо переводит вкладку в idle через десять минут, если процесс Claude умер. Если ждать не хочется, закройте и откройте вкладку — это сбросит локальное состояние, и следующее событие хука начнёт с чистого листа. Для копания в причинах запустите с LOG_LEVELS=hooks=debug,status=debug.

Конфликтует ли он с моим существующим конфигом tmux?

Нет. purplemux запускает изолированный tmux на отдельном сокете (-L purple) со своим конфигом (src/config/tmux.conf). Ваш ~/.tmux.conf и любые существующие tmux-сессии не трогаются.

Стоимость и использование

Экономит ли purplemux деньги?

Напрямую — нет. Но он делает использование прозрачным: стоимость за сегодня / месяц / проект, разбивка токенов по моделям и обратный отсчёт лимитов 5h / 7d на одном экране, чтобы вы могли регулировать темп до того, как упрётесь в стену.

Сам purplemux платный?

Нет. purplemux — это open source под MIT. Использование Claude Code оплачивается Anthropic отдельно.

Уходят ли мои данные куда-то?

Нет. purplemux полностью self-hosted. Единственные сетевые вызовы, которые он делает, — это к локальному Claude CLI (который сам ходит в Anthropic) и проверка версии через update-notifier при запуске. Отключить проверку версии — NO_UPDATE_NOTIFIER=1.

Что дальше

  • Поддержка браузеров — подробная матрица совместимости и известные особенности браузеров.
  • Каталог данных — что делает каждый файл и что можно безопасно удалить.
  • Архитектура — как части складываются вместе, когда нужно копнуть глубже.