Instalador e painel para depois de instalar o sistema: Windows, Linux, Steam Deck e um Homelab que você administra de outro computador.
Não é umbrelOS. Não é um “app store” da comunidade. É o mesmo produto em dois papéis: uma máquina funciona como Homelab; a outra administra e consome.
Instalar · Página Linux · Homelab · CLI · Segurança · Changelog
| Superfície | Para quem | O que você sente |
|---|---|---|
| Windows | PC limpo / pós-format | Bootstrap seguro (dry-run, perfil pequeno, rollback) |
| Control Center | Linux / Steam Deck | App Qt: Homelab, VM Windows, emulação, IA, temas |
| Homelab | Um PC servidor + um PC do sofá | Apps um clique, backup verificável, dashboard HTTPS, Tailscale |
Três regras que não mudam:
- Dry-run antes de mutar. Plano visível; apply só com confirmação.
- Segredo nunca na tela. Hash, referência, arquivo
0600— não cola de API key. - Falha fechada e honesta. Dado ausente aparece indisponível. Sem
latest. Sem abrir a WAN sozinho.
Este é o modelo que o projeto assume. Co-localizar os dois papéis no mesmo computador é opt-in, não o desenho.
flowchart LR
C["Celular · TV · notebook<br/>consomem os serviços"]
A["PC Homelab (appliance)<br/>PhaseZero para FUNCIONAR<br/><br/>compose + backups<br/>Tailscale · agente + mDNS<br/>dashboard web HTTPS"]
B["PC Admin (Player)<br/>PhaseZero para ADMINISTRAR<br/><br/>painel desktop<br/>seletor de host<br/>pareamento SSH / token"]
C -->|Jellyfin · Vaultwarden · Nextcloud| A
B <-->|LAN / Tailscale| A
Mesma topologia em texto puro
Celular, TV, notebook da casa
│ consomem Jellyfin / Vaultwarden / Nextcloud
▼
┌───────────────────────────┐ LAN / Tailscale ┌───────────────────────────┐
│ PC Homelab (appliance) │◄───────────────────────►│ PC Admin (este, Player) │
│ PhaseZero para FUNCIONAR │ │ PhaseZero para ADMINISTRAR│
│ │ │ e CONSUMIR │
│ compose + backups │ │ Player desktop │
│ Tailscale │ │ seletor de host │
│ agente + mDNS │ │ pareamento SSH / token │
│ dashboard web HTTPS │ │ Abrir dashboard │
└───────────────────────────┘ └───────────────────────────┘
| Papel | Onde instala | O que não faz |
|---|---|---|
| Appliance | O outro PC, o que fica ligado | Não precisa de teclado o dia todo |
| Admin / Player | O PC em que você senta | Não sobe Docker da stack Homelab |
Fora de casa o caminho é Tailscale. Não há UPnP nem port-forward.
Uma vitrine categorizada com tudo o que o projeto entrega no Linux. Sem caçar comando no terminal e sem adivinhar o que já está ligado.
Cada cartão mostra:
| Elemento | Para que serve |
|---|---|
| Ícone e nome | Ícone real do app instalado, lido do .desktop. Nada é baixado da internet. |
| Descrição | O que aquilo faz, em uma linha. |
| Interruptor | Ligado = instalado / aplicado. Desligado = ausente. |
| Selo de reversão | Como se desfaz: pacote, Flatpak, arquivo de backup, valor anterior — ou manual/sem reversão, sem pintar de verde o que ninguém desfaz sozinho. |
| Selo de modo | Recomendado, Opcional ou Avançado. |
Três garantias que valem para todo interruptor:
- Prévia antes de mutar. Ligar dispara um plano; nada acontece sem sua confirmação.
- Estado nunca otimista. O interruptor fica em aplicando… e só assume o novo valor quando o host reconfirma. Prévia recusada devolve o botão ao lugar.
- Não sondado ≠ desligado. Se a leitura falhar, o controle fica inerte e diz o motivo, em vez de exibir um "desligado" em que você poderia agir por engano.
O equivalente em linha de comando:
# Recursos: sondar, planejar, aplicar, remover. Toda saída já é JSON.
linux/pz capabilities status
linux/pz capabilities plan --capability gaming.mangohud
linux/pz capabilities apply --plan-id <id-do-plano> --confirm <token>
linux/pz capabilities remove-plan --capability gaming.mangohud
linux/pz capabilities remove --plan-id <id-do-plano> --confirm <token>
# Otimizações por área (gaming | browser | dev).
linux/pz tune gaming status # estado real, com aviso de drift
linux/pz tune gaming apply --dry-run # plano, sem tocar em nada
linux/pz tune gaming revert # volta ao que era seuO id e o token saem do próprio plan/remove-plan: aplicar exige o plano que você
acabou de ver, não um comando solto. O painel faz esse encadeamento por você.
revert guarda o arquivo original e o valor anterior de cada preferência de ferramenta;
o que era seu volta a ser seu, em vez de simplesmente sumir.
Vai contribuir em máquina nova? Use bootstrap e handoff de desenvolvimento. Esse caminho prepara ferramentas de código/teste sem instalar serviços ou VMs do produto. Auditoria do estado atual registra o que ainda falta homologar.
Canal stable: destino Latest, reservado para releases estáveis verificadas. Canal beta: escolher explicitamente uma pré-release na lista de Releases; /latest não seleciona betas quando a flag de pré-release está correta. A release v1.22.14 está publicada incorretamente como estável e ocupa /latest; não trate esse destino como certificação de G2/G3/G4. Publicação stable futura exige despacho manual após aceite real, com docs/releases/v<versão>-acceptance.json versionado na tag: version igual à tag e gates.G2/G3/G4 com state: "verified" e evidence apontando a arquivos docs/ versionados. Cada versão traz 7 artefactos + SHA256SUMS-<versão>.
# exemplo: última estável (substitua a versão pelo nome do ficheiro na Release)
sha256sum -c SHA256SUMS-1.19.0Se a linha do pacote não for OK, pare. Não instale.
| Sistema | Ficheiro | Comando |
|---|---|---|
| Arch / Manjaro / BigLinux | phasezero-control-center-*-any.pkg.tar.zst |
sudo pacman -U ./ficheiro.pkg.tar.zst |
| Debian / Ubuntu | phasezero-control-center_*_all.deb |
sudo apt install ./ficheiro.deb |
| Fedora / openSUSE | phasezero-control-center-*.noarch.rpm |
sudo dnf install ./ficheiro.rpm |
| Qualquer Linux (sem root) | PhaseZero-*-x86_64.AppImage |
chmod +x PhaseZero-*.AppImage && ./PhaseZero-*.AppImage |
| Flatpak | PhaseZero-*.flatpak |
flatpak install --user PhaseZero-*.flatpak |
A instalação acima usa o sudo/pkexec do sistema uma única vez — a bridge
phasezero-admin ainda não existe num host limpo. Em seguida, prepare a
bridge (sem root, uma vez por usuário) e confirme o CLI no PATH:
pz --version # /usr/bin/pz vem no pacote; sem checkout
pz ai setup admin # cria ~/.local/bin/phasezero-admin
pz ai admin status # ready=true antes de qualquer mutaçãoA partir daqui prefira phasezero-admin (ou bigsudo) em vez de sudo sem contexto. Nunca configure sudo sem senha por causa disto.
O pacote instala o binário phasezero-control-center (atalho PhaseZero) e o CLI pz (/usr/bin/pz → linux/pz). A UI só chama pz com argumentos de um catálogo fechado; o acesso remoto (SSH) usa pz com fallback para /usr/lib/phasezero/linux/pz.
Windows: bootstrap-ui.bat / install-cli.bat no checkout; PowerShell 5.1. Perfis safe-base (default) e full-workstation (opt-in). Sem result.json a corrida é erro do produto. Detalhe abaixo.
PC A — appliance (o outro computador, o que fica ligado)
phasezero-control-center # ou: linux/pz ui
# Perfil Servidor / Homelab → Preparar (repair) → Prévia → LigarEquivalente CLI, sempre com plano primeiro:
linux/pz server homelab plan --json
linux/pz server homelab repair --access local
linux/pz server homelab apps list --json
linux/pz server homelab apps enable vaultwarden --json
linux/pz server homelab backupBind default: 127.0.0.1. Acesso na casa: Tailscale. Restore nunca leva --yes automático — confirmação em duas etapas.
PC B — admin (este computador, o que você usa)
- Instale o mesmo pacote da Release (checksum conferido).
- Abra o Player → categoria Homelab.
- Não clique em “Subir homelab” neste PC. Aqui o papel é administrar o outro.
Host→ adicionaruser@ip-do-appliance→ Parear (chave SSH, sem senha no argv).- Cards um clique (prévia / ligar / atualizar) e Abrir dashboard (HTTPS do appliance).
Primeira conta do dashboard web nasce só no CLI/Player do appliance:
linux/pz server homelab web user add SEU_USER --password-file ./senha.txt --jsonA web recusa signup aberto. Cookie: Secure, HttpOnly, SameSite=Strict. Sem CSRF → 403.
Máquina limpa, PowerShell 5.1. Perfil default pequeno (safe-base). full-workstation só por opt-in. A UI WPF e o CLI compartilham o mesmo contrato: log, result.json, falha acionável. Reboot pendente bloqueia winget/MSI arriscado.
bootstrap-ui.bat # painel
install-cli.bat # CLI
Perfil steamdeck-linux: Gamepad UI, atalhos, teclado virtual, watcher de dock. Avançado (Handheld Companion / GlosSI) é opt-in porque conflita com Steam Input.
No Control Center, Boot Direto → Login do host → Entrar no KDE sem senha. No CLI: linux/pz boot kde-login plan enable, linux/pz boot kde-login enable e linux/pz boot kde-login status. Para reverter: linux/pz boot kde-login disable. O ajuste escolhe a conta local invocadora e a sessão Wayland plasma.desktop; um shell root sem identidade confiável exige --user USER. Ativação e reversão exigem administração e passam a valer no próximo início do SDDM. Não reiniciam a sessão atual.
A preferência KDE vale para o boot Linux normal. Entradas diretas Steam Deck, Windows VM e Waydroid mantêm suas configurações de sessão. Configurações SDDM posteriores que também definem login automático bloqueiam a ativação até resolver o conflito. Relogin=true reabre o KDE após sair; use bloqueio de tela para deixar a sessão protegida. Login automático não destranca KWallet nem substitui senha de administração.
pz windows-vm: ISO que você indica. Sem download de ISO/chave. QEMU/KVM, OVMF, TPM 2.0. Detecta domínio libvirt já instalado antes de criar disco.
Launchers e layout ~/Emulation. BIOS, keys, ROMs: só importação local de dumps seus. PhaseZero não baixa ROM/BIOS.
Roteamento e proxies no Control Center. Segredos no cofre gerido; stdout JSON sem valores crus. 9Router recusa subir se HOSTNAME/PORT estiverem vazios (não volta a bind 0.0.0.0:3000).
DeepSeek Harness oficial (Experimental): IA & Dev oferece instalação, escolha de conta/API, pasta e porta, abertura Web, parada e diagnóstico. Modo avançado reúne prévia, atualização por versão fixada e remoção com dados preservados. Contas e conexões leva à mesma ficha. Node fica no runtime privado; instalar não inicia o agente. Login, cota e isolamento exigem validação própria. Não usa DeepSeek Proxy nem habilita fallback para API paga. Operação e limites.
Conectar já sugere pasta do projeto, com opção Trocar pasta. Entrar com DeepSeek usa OAuth oficial no navegador; Usar chave API permite selecionar chave DeepSeek da carteira PhaseZero ou guardar nova chave no cofre do sistema. Uso/cobrança exige confirmação. Chave selecionada segue apenas para o processo API correspondente, sem aparecer em argumentos ou logs; removê-la da carteira interrompe esse runtime gerenciado. Validade, saldo e cota continuam separados.
Dashboard IA & Dev: agentes/ferramentas instalados, serviços ativos, memória, MCPs/rotas, perfis de eficiência e Harness aparecem em resumo visual; lista expansível mostra componentes individuais. Franquias e assinaturas ficam logo abaixo. Falha de leitura aparece como desconhecida, sem inventar estado saudável.
Codex Web já habilitado por opt-in: Atualizar app mantém login e preferências, migra runtime e hook juntos e retoma uma configuração incompleta com o pacote local verificado. Preparar ou reparar usa a mesma recuperação. Feche somente o Codex do perfil Web antes de reiniciar a integração. Estado pronto exige rota ativa e bridge respondendo; teste com mensagem continua explícito.
Em Contas Codex → Web, padrão automático habilita Pro/Pro Lite e desabilita demais planos, plano desconhecido ou assinatura observada vencida. Preferência pode ser ajustada por conta. Janela e ícone Web recebem cor exclusiva, distinta dos perfis nativos. Abrir Web exige modo com ferramentas e validação de túnel/conector; Verificar conexão separa conexão apta de execução real comprovada. Permissões do host e login de cada conta continuam necessários.
Para instalar o Harness no host, use IA & Dev → DeepSeek Harness → Instalar
ou pz ai deepseek-harness install --json. A instalação é separada de iniciar;
para conferir, execute pz ai deepseek-harness doctor --json. Versões fixadas:
DSH 0.2.1-rc.2 e Node 24.22.0. Arquivos Node/npm para Linux x64 somam
171.671.463 bytes (~164 MiB), antes de eventuais downloads dos hooks nativos.
Neste workspace, downloads acima de 70 MB precisam ser iniciados manualmente
pelo operador. Parâmetros, origens e validação.
Memória dos agentes: IA & Dev reúne instalar/reparar, projetos compartilhados, dispositivos cadastrados, GitHub privado, sincronização manual/automática e restauração verificada. Conhecimento circula entre hosts; backup completo mantém histórico por equipamento. Conteúdo remoto sai criptografado; chave fica no cofre do sistema. Exporte recuperação antes de depender de outro host. Configuração, recuperação e evidências.
O que o produto não finge:
- Componente Windows sem prova de auditoria vira
UnsupportedAudit, nunca “ok”. - Sem
result.jsona execução é falha do produto, não silêncio. - Homelab neste PC de desenvolvimento não recebe
upda stack. Appliance é o outro computador. - BIOS, ROM, ISO e chaves de consola não são descarregados.
| Tema | Comportamento |
|---|---|
| Imagens Docker | Tags pinadas no lock. Recusa :latest. |
| Socket Docker | Só o socket-proxy read-only. Nada monta docker.sock. |
| Backup | manifest.json + SHA-256. Restore verifica; adulterado recusa. |
| Bind | Loopback por omissão. LAN só com opt-in persistido. Sem UPnP. |
| Agente remoto | TLS + token one-shot (15 min). Allowlist. Kill switch local. |
| Dashboard web | HTTPS, CSRF, senha argon2id (scrypt se a lib faltar). 2FA ainda não. |
Documentação profunda: docs/linux-homelab.md · roadmap docs/roadmaps/homelab-umbrelos-parity-v1.md · ADRs docs/adr/0003-homelab-agent-mdns.md e docs/adr/0004-homelab-web-dashboard.md.
linux/pz help
linux/pz ui # Control Center
linux/pz server homelab status --json
linux/pz server homelab hosts add garage 'user@192.168.1.8' --json
linux/pz server homelab --host garage apps list --json
linux/pz server homelab discover --jsonCatálogo completo de ações: a própria UI e linux/ui/actions.json (gerado, não editar à mão).
CI (.github/workflows/ci.yml): parse PowerShell, Pester 3.4.0, ShellCheck 0.9 e 0.11, pytest, compose validate, gitleaks. Docker só em jobs descartáveis (PZ_HOMELAB_APPS_DISPOSABLE=1 + estado em /tmp ou RUNNER_TEMP). O runner genérico não executa esses scripts.
Release canónica:
packaging/release.sh 1.19.0 --push # bump, tag anotada, dispara o workflowTags históricas não se movem. Confira sempre o SHA256SUMS da versão que vai instalar.
PhaseZero não substitui o instalador do Windows nem o umbrelOS. Não distribui ISOs, ROMs, BIOS nem chaves de consola. Contribuição de apps Homelab: PR no catálogo do repositório, não loja comunitária.
Perfis de eficiência por agente/projeto, memória permanente e medição sem inferência paga: contrato e operação.