phone-deck

Transforme um telefone Android sobressalente (ou qualquer dispositivo com navegador) em um painel de controle auto-hospedado e área de trabalho remota para sua estação de trabalho Linux — através de sua rede Tailscale privada, sem aplicativos de terceiros.

Começou como "o que fazer com um telefone antigo?" e se tornou um plano de controle para um rig Hyprland: controle de janela/workspace, macros de cena, um roteador de voz push-to-talk com assistente LLM local, controles contextuais no aplicativo, áudio bidirecional + streaming de tela, uma área de trabalho remota por toque, um teclado/mouse virtual, transferência de arquivos + compartilhamento telefone→PC, e telemetria ao vivo — tudo servido como um PWA instalado com aparência de terminal fósforo.

Nota sobre portabilidade. Isto foi construído para uma configuração específica: Linux baseado em Arch (Garuda) + Hyprland + PipeWire + NVIDIA + Tailscale, com os dotfiles end-4 / illogical-impulse. A arquitetura é genérica, mas várias integrações são específicas do ambiente (nomes de monitores, vinculações de workspaces, o caminho do tema matugen, cpupower/nvidia-smi). Trate como uma referência funcional para adaptar, não um pacote chave na mão.

Funcionalidades

A interface é um aplicativo web com abas, escuro, em modo paisagem (sincronizado com o tema do seu desktop):

Sempre ativa, acima das abas — uma faixa de contexto que mostra o que está acontecendo agora: uma chamada ativa (mudo / pule para ela), mídia reproduzindo agora + transporte, e controles de teclado no aplicativo para o aplicativo focado (YouTube / Brave / Teams), entregues sem roubar o foco.

Dois recursos adicionais, além das abas:

• Send-to-Rig — o PWA se registra como um destino de compartilhamento do Android: compartilhe uma imagem, um texto ou um link de qualquer aplicativo no seu telefone e ele chega ao rig — imagens salvas em um diretório de drop e colocadas na área de transferência como PNG pronto para colar, texto na área de transferência, um link simples aberto.
• Ambient Cogitator — após alguns minutos de inatividade, o painel se torna um painel de instrumentos fósforo: telemetria com mostrador de agulha e pico retido ("esteve no máximo enquanto eu estava longe?"), relógio, reprodução agora.

Além disso: login com PIN numérico na tela, wake-lock de tela, PWA em tela cheia paisagem e bloqueio de força bruta no login.

Arquitetura

   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, …)

Dois processos:

• app/ — o aplicativo web é executado como seu usuário normal. Ele faz tudo que não precisa de root: controle do Hyprland, áudio, brilho, captura de tela, entrada virtual, streaming WebRTC, transferência de arquivos.
• deckd/ — um pequeno helper root (apenas stdlib, sem dependências) para as poucas ações privilegiadas. O aplicativo web nunca envia strings de shell para ele — apenas nomes de ações de uma lista de permissões fixa (governor_performance, gpu_power_limit, suspend, …), validados em deckd/actions.py antes de qualquer execução. Mesmo que o aplicativo web seja totalmente comprometido, o raio de explosão é exatamente as ações permitidas, sem injeção de argumentos. O socket é root:<group> modo 0660.

Modelo de segurança

• Acessível apenas dentro da sua tailnet — tailscale serve expõe no seu nome MagicDNS com um certificado Let's Encrypt real; nunca liga em 0.0.0.0.
• JWT login (PIN → cookie assinado), com bloqueio com backoff exponencial após falhas repetidas.
• Ações privilegiadas são isoladas atrás do daemon helper com lista de permissões.
• Uploads são sanitizados por basename (não podem escapar do diretório de drop).

Nota: O aplicativo web pode executar seus comandos de shell configurados e injetar entrada como seu usuário — é, por design, um controle remoto para sua máquina. Mantenha-o em sua tailnet, atrás do PIN, e não o exponha publicamente.

Requisitos

• Linux com Hyprland (wlroots), PipeWire (com compatibilidade pactl/PulseAudio)
• Python ≥ 3.11 e uv
• Tailscale (com certificados HTTPS habilitados para sua tailnet)
• Ferramentas CLI usadas por vários recursos (instale o que deseja usar): hyprctl, pactl / pw-record / pw-play, playerctl, ddcutil, wf-recorder, grim, cpupower, nvidia-smi, kitty (ou seu terminal)
• Seu usuário no grupo input (para ) e (para )

Instalação

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. O helper root (deckd)

Edite systemd/deckd.service primeiro — defina os caminhos e DECK_SOCKET_GROUP para um grupo ao qual seu usuário pertence (geralmente seu grupo primário):

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

deckd é executado com o Python do sistema (apenas stdlib — sem necessidade de venv).

2. O aplicativo web

Execute diretamente para desenvolvimento:

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

…ou como um serviço de usuário. Edite os caminhos de systemd/phone-deck.service primeiro, depois instale-o. Importante: em uma configuração onde o Hyprland não é iniciado via uwsm, o target graphical-session.target do systemd nunca é ativado, então a unit de usuário não será iniciada automaticamente no login. A correção confiável é iniciá-lo a partir do Hyprland com o ambiente de sessão importado — adicione ao autostart do Hyprland (ex: ~/.config/hypr/custom/execs.conf do end-4):

exec-once = systemctl --user import-environment WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_RUNTIME_DIR DBUS_SESSION_BUS_ADDRESS XDG_CURRENT_DESKTOP && systemctl --user start phone-deck

3. HTTPS via Tailscale

1. Habilite os certificados uma vez: Console de administração Tailscale → DNS → Enable HTTPS Certificates.

2. Coloque o aplicativo atrás de um certificado real:

   root@kitploit:~

   sudo tailscale serve --bg 127.0.0.1:8765
   

3. Defina DECK_SECURE_COOKIES=1 no ambiente do aplicativo web assim que HTTPS estiver ativo.

4. Instalar no telefone

Abra https://<seu-host>.<sua-tailnet>.ts.net/ no Chrome no telefone (ele deve estar na sua tailnet), faça login, então ⋮ → Install app. Ele inicia em tela cheia, bloqueado em modo paisagem, com a tela mantida ativa. HTTPS é necessário para o service worker do PWA + wake-lock.

Funciona de qualquer dispositivo na tailnet — laptops incluídos (as superfícies de toque usam Pointer Events, então um mouse também funciona). O stream WebRTC é de par único (um visualizador por vez).

Configuração

Toda configuração em tempo de execução reside em ~/.config/phone-deck/ e é editável na aba Config (validado JSON, mantém um .bak). As alterações entram em vigor na próxima ação — sem reinicialização.

commands.json — ações de shell personalizadas

[
  { "id": "reload_wm", "label": "Reload WM", "run": "hyprctl reload" },
  { "id": "deploy", "label": "Deploy site", "run": "cd /srv/app && ./deploy.sh",
    "confirm": true, "timeout": 120 }
]

run pode ser uma string (executada via bash -lc) ou uma lista (argv, sem shell). Estes são executados como seu usuário — é um arquivo local e confiável.

modes.json — macros de cena

Cada modo é uma lista ordenada de etapas executadas via hyprctl:

• launch {cmd, workspace, match?, once?} — abre um aplicativo em um workspace. Com match (classe da janela) + once, não duplica, e realoca a janela se ela cair no workspace errado (necessário para aplicativos como PWAs de navegador cuja janela vem de um processo existente).
• close {match, workspaces?} — fecha janelas de uma classe, opcionalmente apenas nos workspaces listados.
• move {match, workspace} — move janelas correspondentes para um workspace.
• focus {workspace} — alterna um workspace para visualização (ex: redefinir cada monitor para seu workspace inicial).

Vinculação de workspace Hyprland → monitor

O posicionamento do modo é determinístico apenas se seus workspaces estiverem fixados em monitores. Adicione vinculações à sua configuração do Hyprland (ajuste números de workspace e nomes de monitores para os seus):

workspace = 1, monitor:DP-3, default:true
workspace = 2, monitor:DP-3
# … etc

Tema

O deck usa uma skin phosphor-terminal com quatro perfis de cor alternáveis ao vivo — green (padrão), amber, ice e auto (deriva o matiz phosphor da paleta de wallpapers do matugen, ~/.local/state/quickshell/user/generated/colors.json). Alterne na aba System; a escolha persiste em ~/.config/phone-deck/theme.json. app/theme.py o serve como /theme.css. O tempo limite de inatividade do Ambient Cogitator e a linha de liturgia também são configuráveis aqui.

Como o streaming funciona

WebRTC bidirecional via aiortc + PyAV, conectado ao PipeWire/Hyprland com pipes de subprocesso (evita associações frágeis de E/S de dispositivo):

• PC → áudio do telefone: captura o .monitor do sink padrão com parec → Opus.
• Telefone → microfone PC: recebe o microfone do telefone → um sink nulo do PipeWire cujos aplicativos de monitor selecionam como entrada ("Monitor of PhoneDeckMic").
• Saída apenas no telefone: roteia a reprodução do PC para um sink virtual para que os alto-falantes fiquem silenciosos enquanto você ouve no telefone; restaurado na parada.
• PC → vídeo do telefone: wf-recorder captura um monitor → aiortc, com predefinições de qualidade (540p / 720p / 1080p) para manter a taxa de bits razoável em links instáveis.
• Área de trabalho remota por toque: tocar/arrastar no vídeo transmitido → posicionamento absoluto do cursor (hyprctl movecursor) + cliques uinput. Toque = clique, arrastar = mover, toque longo = clique direito.

Restrições: latência de ~150–300 ms; confiável apenas enquanto o PWA está em primeiro plano (Android suspende abas em segundo plano); use fones de ouvido para evitar eco; um par de streaming por vez; um navegador não pode capturar o áudio do próprio aplicativo do telefone (apenas microfone).

Stack tecnológica

• Backend: FastAPI + Uvicorn, WebSockets, aiortc/PyAV, python-evdev, psutil, PyJWT
• Frontend: HTML + Tailwind (CDN) + vanilla JS, PWA (manifesto + service worker + wake-lock)
• Daemon auxiliar: Apenas biblioteca padrão Python
• Transporte: Tailscale (tailscale serve para HTTPS/WSS)

Testes

uv run pytest

Cobre a lista de permissões do deckd, JWT + bloqueio de login, hash de PIN, validação do editor de configuração, análise de modos, lógica de qualidade/comando de streaming e o mapa de teclado de entrada. Os caminhos ao vivo WebRTC/PipeWire/Hyprland são validados por loopback durante o desenvolvimento.

Estrutura do projeto

app/          FastAPI web app
  main.py       routes + WebSockets
  hypr.py       Hyprland (snapshot, dispatch, event socket, cursor)
  audio.py      PipeWire device control + playerctl
  audio_rtc.py  WebRTC audio + screen video bridge
  hid.py        virtual keyboard/mouse via uinput
  modes.py      scene-macro engine
  brightness.py ddcutil
  grab.py       screenshot + file upload
  theme.py      matugen → CSS
  ...
deckd/        root helper (stdlib only) + action allowlist
systemd/      service units
tests/        pytest suite

Licença

MIT — veja LICENSE (adicione um antes de publicar se quiser uma licença diferente).

Agradecimentos

Construído para Hyprland, PipeWire, Tailscale, aiortc e os dotfiles do end-4.