phone-deck

Превратите запасной телефон на Android (или любое устройство с браузером) в собственный пульт управления и удаленный рабочий стол для вашей Linux-рабочей станции — через вашу частную сеть Tailscale, без сторонних приложений.

Это началось с вопроса «что мне делать со старым телефоном?» и превратилось в управляющую плоскость для системы Hyprland: управление окнами/рабочими столами, сценарные макросы, голосовой маршрутизатор PTT с локальным LLM-ассистентом, контекстно-зависимые элементы управления в приложении, двустороннее аудио + трансляция экрана, сенсорный удаленный рабочий стол, виртуальная клавиатура/мышь, передача файлов + отправка с телефона на ПК и телеметрия в реальном времени — всё это предоставляется в виде установленного PWA с фосфорным терминальным оформлением.

Примечание о переносимости. Этот инструмент создавался для одной конкретной конфигурации: Arch-based Linux (Garuda) + Hyprland + PipeWire + NVIDIA + Tailscale с dotfiles end-4 / illogical-impulse. Архитектура универсальна, но многие интеграции зависят от окружения (имена мониторов, привязки рабочих столов, путь к теме matugen, cpupower/nvidia-smi). Воспринимайте это как рабочий справочник для адаптации, а не готовое решение.

---

Возможности

Интерфейс представляет собой веб-приложение с вкладками, темное, ландшафтное (синхронизировано по теме с вашим рабочим столом):

Вкладка	Что делает
Рабочие столы	Сетка рабочих столов для каждого монитора в реальном времени (нажатие для переключения), список окон в реальном времени (нажатие для фокуса), переключатель DPMS для каждого монитора + яркость ddcutil
Удаленное управление	Экранная тачпад (перетаскивание/нажатие/два пальца) + виртуальная клавиатура с модификаторами и комбинациями, через устройство ядра uinput
Режимы	Макросы сцен одним нажатием — запуск/закрытие/расположение целых макетов приложений на нескольких мониторах (например, «Работа» / «Отдых»)
Голос	Голосовой маршрутизатор PTT (faster-whisper, CPU): полосы ключевых слов — macro (запуск режима/команды), type (диктовка), input (фраза → клавишная комбинация) — с подтверждением перед выполнением, а также "friday", readonly локальный LLM-ответчик (Ollama + Qwen) с собственным веб-поиском и отслеживанием состояния системы в реальном времени
Аудио	Отключение микрофона/динамика, громкость, выбор устройств вывода и ввода, транспорт playerctl + обложка (отслеживает активный MPRIS-плеер)
Поток	Двустороннее WebRTC аудио (ПК↔телефон, с телефоном в качестве микрофона и только вывод на телефон) + видео экрана, и нажатие для управления транслируемым экраном = настоящий удаленный рабочий стол
Система	Переключатель режима производительности, живое переключение темы, статус Tailscale, топ-процессы (нажатие для завершения), блокировка, перезапуск NetworkManager, приостановка/перезагрузка/выключение
Файлы	Сделать снимок экрана монитора → просмотр/скачивание на телефоне; перетащить файл с телефона на ПК
Настройки	Редактирование конфигурации commands.json / modes.json (и контекстных/голосовых) с телефона (проверка JSON)

Всегда поверх вкладок — контекстная полоса, показывающая, что происходит прямо сейчас: активный звонок (отключение / переход к нему), воспроизводимый медиаконтент + транспорт, и внутриприкладные элементы управления клавиатурой для активного приложения (YouTube / Brave / Teams), без перехвата фокуса.

Еще две функции за пределами вкладок:

• Send-to-Rig — PWA регистрируется как цель обмена в Android: поделитесь изображением, текстом или ссылкой из любого приложения на телефоне, и они окажутся на компьютере — изображения сохраняются в каталог сброса и помещаются в буфер обмена как готовый к вставке PNG, текст в буфер обмена, голая ссылка открывается.
• Ambient Cogitator — после нескольких минут бездействия пульт превращается в фосфорную приборную панель: стрелочные измерители телеметрии с фиксацией пиков («было ли на пределе, пока меня не было?»), часы, текущее воспроизведение.

Плюс: вход с помощью экранной цифровой клавиатуры PIN, блокировка пробуждения экрана, полноэкранное ландшафтное PWA и блокировка при переборе паролей при входе.

---

Архитектура

   phone / laptop (browser PWA)
            │  HTTPS + WSS  (Tailscale-only)
            ▼
   tailscale serve  ──►  FastAPI web app   ── Unix socket ──►  deckd
   (real TLS cert)       (runs as your user)   (action names)   (runs as root)
                              │                                  │
              hyprctl · pactl · ddcutil · grim ·          fixed allowlist of
              wf-recorder · uinput · WebRTC               privileged commands
                                                          (cpupower, nvidia-smi,
                                                           systemctl, …)

Два процесса:

• app/ — веб-приложение работает от имени обычного пользователя. Оно выполняет всё, что не требует прав root: управление Hyprland, аудио, яркость, захват экрана, виртуальный ввод, WebRTC-стриминг, передача файлов.
• deckd/ — крошечный помощник с правами root (только stdlib, без зависимостей) для нескольких привилегированных действий. Веб-приложение никогда не отправляет ему строки shell — только имена действий из фиксированного разрешенного списка (governor_performance, gpu_power_limit, suspend, …), проверяемые в deckd/actions.py перед выполнением. Даже если веб-приложение будет полностью скомпрометировано, радиус поражения ограничен разрешенными действиями без возможности внедрения аргументов. Сокет имеет права root:<group> режим 0660.

Модель безопасности

• Доступно только внутри вашей tailnet — tailscale serve предоставляет доступ по вашему имени MagicDNS с реальным сертификатом Let's Encrypt; никогда не привязывается к 0.0.0.0.
• Вход по JWT (PIN → подписанная кука) с блокировкой с экспоненциальной задержкой после повторных неудач.
• Привилегированные действия изолированы за разрешенным демоном-помощником.
• Загрузки очищаются от базового имени (невозможно покинуть каталог сброса).

Веб-приложение может выполнять ваши настроенные shell-команды и вводить данные от вашего имени — по замыслу, это пульт управления вашей машиной. Держите его внутри tailnet, за PIN-кодом, и не выставляйте публично.

---

Требования

• Linux с Hyprland (wlroots), PipeWire (с совместимостью pactl/PulseAudio)
• Python ≥ 3.11 и uv
• Tailscale (с включенными HTTPS-сертификатами для вашей tailnet)
• Инструменты командной строки, используемые различными функциями (установите то, что хотите использовать): hyprctl, pactl / pw-record / pw-play, playerctl, ddcutil, wf-recorder, grim, cpupower, nvidia-smi, kitty (или ваш терминал)
• Ваш пользователь в группе input (для /dev/uinput) и i2c (для ddcutil)
• aiortc + PyAV (устанавливается через uv) для аудио/видео стриминга

---

Установка

git clone <your-repo-url> phone-deck
cd phone-deck
uv sync                          # creates .venv and installs dependencies
uv run python -m app.set_pin     # set your unlock PIN

1. Помощник с правами root (deckd)

Сначала отредактируйте systemd/deckd.service — укажите пути и DECK_SOCKET_GROUP в группу, к которой принадлежит ваш пользователь (обычно основная группа):

sudo cp systemd/deckd.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now deckd

deckd запускает системный Python (только stdlib — venv не нужен).

2. Веб-приложение

Запустите напрямую для разработки:

uv run uvicorn app.main:app --host 127.0.0.1 --port 8765