Containers, Compose, VMs Linux, Kubernetes e domínios locais em um único app — sobre o Podman Engine nativo.
Alternativa Linux ao OrbStack, com Qt 6/QML, daemon de usuário e CLI scriptable.
Status: M4 validado em VM real e M5 concluído no código — machines QEMU/KVM (ciclo de vida, SSH/arquivos, virtiofs, export/import, clone/rename/default, recursos, portas, agent forwarding, modo isolado, console serial e snapshots), sobre o M3 (Compose e builds), o M2 (imagens, volumes, redes e pods) e o M1 (containers, logs, stats, files, terminal, batch, health e rootful). Pré-M5 entregue com multi-seleção em todas as listas, testes QML reais e gates de
clang-format/clang-tidy. 15 testes, cobertura ~80% com gate bloqueante de 80% (verdocs/sdd/testing.md). M5 (Kubernetes/k3s) concluído no código (VM dedicada, kubeconfig isolado, Pods/Services, logs, port-forward, enable/disable/reset e contexto). M6 iniciado com a T6-01:*.localhostvia proxy HTTP do daemon em loopback (network.httpPort), sem root e sem/etc/hosts. Ressalvas: console serial sem VNC; export/clone não preservam snapshots internos do qcow2; a instalação limpa tem smoke automatizado em container Fedora 44 (scripts/clean-install-check.sh), mas a validação da GUI, do KVM e do polkit em máquina limpa segue manual (T7-07/T7-14). Histórico de versões emCHANGELOG.mde guias emdocs/user/. Plataforma: Linux desktop — Fedora 43+ (Podman ≥ 5.8, Qt ≥ 6.10) e Ubuntu 24.04+ (Podman ≥ 4.9, Qt ≥ 6.4; DEB), Wayland/X11. Identidade: projeto independente, sem afiliação com a Orbital Labs. Nenhum asset, ícone ou código proprietário do OrbStack é reutilizado (verdocs/sdd/constitution.md).
O PodStack reúne, em uma única experiência desktop:
- Containers: ciclo de vida, logs, terminal, arquivos, estatísticas e inspect.
- Imagens, volumes, redes e pods com gestão visual.
- Compose: projetos agrupados, logs por serviço, up/down.
- Machines: VMs Linux (Ubuntu, Debian, Fedora, Arch, Alpine e outras) com cloud-init, SSH, virtiofs e port forwarding.
- Kubernetes local integrado, com contextos e kubectl.
- Domínios locais (
*.localhost/*.podstack.local) e HTTPS automático. - CLI
podstackcom paridade com a GUI, para automação e CI. - Rootless por padrão, com helper privilegiado mínimo e opt-in.
Arquitetura em uma frase: GUI Qt Quick + CLI + podstackd conversando por JSON-RPC em Unix socket; o daemon fala com o podman.socket via Libpod REST, com QEMU/KVM para machines, Caddy para HTTPS e k3s para Kubernetes.
A documentação é a fonte de verdade e segue SDD (Spec-Driven Development): constituição → PRD → spec → plan → tasks.
| Documento | O que responde |
|---|---|
docs/README.md |
Índice geral, convenções e mapa SDD |
docs/sdd/constitution.md |
Princípios inegociáveis (clean-room, rootless, segurança, qualidade) |
docs/sdd/PRD.md |
PRD completo: problema, personas, 127 requisitos funcionais, 32 NFRs, métricas, riscos e critérios de release |
docs/sdd/spec.md |
Comportamento detalhado, fluxos, máquinas de estado e casos de borda |
docs/sdd/plan.md |
Plano técnico: stack, componentes, concorrência, persistência e riscos |
docs/sdd/tasks.md |
133 tarefas em M0–M8, com dependências e definição de pronto |
docs/sdd/testing.md |
Pirâmide de testes, matriz de compatibilidade, CI e performance |
| Documento | O que responde |
|---|---|
docs/user/README.md |
Índice da documentação de usuário e limitações conhecidas do 0.1.3 |
docs/user/install.md |
Requisitos, instalação por RPM/DEB, build do fonte, primeiro start, setup, helper/polkit e desinstalação |
docs/user/quickstart.md |
Primeiro container, machine com SSH, Kubernetes, domínios *.localhost, HTTPS/CA, bandeja e atalhos |
docs/user/cli.md |
Comandos e flags reais do podstack, saída JSON, exit codes e exemplos |
docs/user/troubleshooting.md |
Diagnóstico de daemon, Podman, helper, KVM, SSH, portas, firewall, CA, DNS e erros PODSTACK_* |
| Documento | Conteúdo |
|---|---|
docs/engineering/architecture.md |
C4, sequências (exec, logs, machines, domínios, K8s), threads e erros |
docs/engineering/data-model.md |
Entidades, esquema SQLite, config.json, meta.json e migrações |
docs/engineering/api-rpc.md |
Contrato JSON-RPC completo do podstackd |
docs/engineering/ui-map.md |
Telas, sidebar, inspector, componentes QML, design tokens e atalhos |
docs/engineering/branding.md |
Logo, paleta, tipografia e regras de uso dos assets |
docs/engineering/cli-parity.md |
Mapa orb → podstack, flags, exit codes e exemplos |
docs/engineering/settings.md |
Todas as chaves, defaults, validação e migração |
docs/engineering/security.md |
Threat model, helper/polkit, socket, segredos e SELinux |
docs/engineering/packaging.md |
RPM, systemd, polkit, SELinux, AppImage e avaliação de Flatpak |
docs/sdd/roadmap.md |
Marcos, estimativas, caminho crítico e versões |
CHANGELOG.md |
Histórico de versões, mudanças e limitações conhecidas do 0.1.3 |
| ADR | Decisão |
|---|---|
0001 — Daemon JSON-RPC |
Daemon de usuário com JSON-RPC sobre Unix socket |
0002 — Libpod + libcurl |
Libpod REST e libcurl para streams/hijack |
0003 — Machines QEMU/KVM |
QEMU/KVM direto + cloud-init + virtiofs |
0004 — Domínios |
*.localhost no v1; *.podstack.local via helper |
0005 — Terminal |
QTermWidget (GPL-2.0-or-later, compatível com GPL-3.0-or-later) |
0006 — RPM primeiro |
RPM como formato primário |
0007 — Compose |
Provider Docker Compose + estado por labels |
| Documento | Conteúdo |
|---|---|
docs/reference/orbstack-2.2.5.md |
Inventário estático do DMG: arquitetura, UI, CLI e settings |
docs/reference/orbstack-2.2.5-official-notes.md |
Correções e detalhes da documentação oficial |
docs/reference/cli-tree.json |
Árvore completa do CLI (51 nós, flags) |
docs/reference/cli-tree.md |
Versão legível da árvore |
docs/reference/swift-files.txt |
29 arquivos de tela/modelo Swift identificados |
docs/reference/settings-keys.txt |
Chaves de settings observadas |
Marca aprovada: cápsula (símbolo principal) + camadas (símbolo secundário). O monograma P não foi aprovado.
| Asset | Descrição |
|---|---|
assets/podstack-logo.svg |
Lockup horizontal (cápsula + wordmark) |
assets/podstack-capsule.svg |
Símbolo principal (cápsula) |
assets/podstack-layers.svg |
Símbolo secundário (camadas) |
assets/podstack-capsule-small.svg |
Cápsula compacta para 16–24 px |
assets/podstack-icon.svg |
Ícone do app (256×256) |
assets/png/ |
Ícones PNG 16–512 e bandeja 16/22/24/32/48/64 |
assets/favicon.ico / favicon-32.png |
Favicon multi-size e PNG 32×32 |
assets/og-image.png / og-image.svg |
Open Graph 1200×630 |
assets/podstack_logo_concepts.svg |
Folha histórica de conceitos |
assets/logo.md |
Racional original dos conceitos |
Paleta: índigo #3730A3, acento #6366F1, ciano #22D3EE. Regras de uso, tamanhos mínimos e o que evitar estão em docs/engineering/branding.md.
.
├── README.md # este arquivo
├── AGENTS.md # instruções para agentes/devs iniciando no projeto
├── CHANGELOG.md # histórico de versões e limitações conhecidas
├── LICENSE # GPL-3.0-or-later
├── NOTICE # aviso de copyright/licença
├── assets/ # marca aprovada (cápsula + camadas)
│ ├── podstack-logo.svg
│ ├── podstack-capsule.svg
│ ├── podstack-layers.svg
│ ├── podstack-capsule-small.svg
│ ├── podstack-icon.svg
│ ├── podstack_logo_concepts.svg
│ ├── favicon.ico
│ ├── favicon-32.png
│ ├── og-image.svg
│ ├── og-image.png
│ ├── png/
│ │ ├── podstack-icon-{16,24,32,48,64,128,256,512}.png
│ │ └── tray/
│ └── logo.md
├── docs/ # especificação, PRD, arquitetura, ADRs e referência
├── README.md
├── constitution.md
├── PRD.md
├── spec.md
├── plan.md
├── tasks.md
├── architecture.md
├── data-model.md
├── api-rpc.md
├── ui-map.md
├── branding.md
├── cli-parity.md
├── settings.md
├── security.md
├── testing.md
├── packaging.md
├── roadmap.md
├── adr/
└── reference/
├── CMakeLists.txt
├── CMakePresets.json
├── src/
│ ├── core/
│ ├── podman/
│ ├── daemon/
│ ├── cli/
│ └── gui/
├── tests/
├── packaging/
├── scripts/
└── .github/workflows/
| Marco | Entrega |
|---|---|
| M0 | Scaffold, daemon, cliente Podman, CLI base, shell QML |
| M1 | Containers: ciclo de vida, logs, terminal, stats |
| M2 | Imagens, volumes, redes, pods |
| M3 | Compose, builds, eventos |
| M4 | Machines (QEMU/KVM, cloud-init, SSH, virtiofs) |
| M5 | Kubernetes (k3s) |
| M6 | Domínios, HTTPS, port forwarding |
| M7 | Tray, settings, updates, v1.0 |
| M8 | USB/serial, X11/áudio, migração (pós-v1) |
Detalhes e critérios de saída em docs/sdd/roadmap.md.
# dependências (Fedora)
sudo dnf install cmake ninja-build gcc-c++ \
qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtwayland-devel \
qtermwidget-devel libarchive-devel libcurl-devel libxcrypt-devel sqlite-devel \
openssh-clients
# provider Compose (runtime, para projetos Compose)
# O binário é docker-compose, mas a engine continua sendo Podman (Libpod REST).
sudo dnf install docker-compose
# build
cmake --preset dev
cmake --build --preset dev
ctest --preset dev
# rodar daemon + GUI (build incremental)
./scripts/dev.sh
# depois do primeiro build, sem recompilar:
PODSTACK_SKIP_BUILD=1 ./scripts/dev.sh
# opcional: desktop entry no perfil do usuário para a dock/menu mostrarem
# o ícone do PodStack em dev (sem instalar o pacote)
./scripts/install-dev-desktop.sh
./scripts/install-dev-desktop.sh --uninstallO scripts/dev.sh usa $XDG_RUNTIME_DIR/podstack/control.sock, inicia o daemon se necessário e reaproveita um daemon já ativo. Para isolar do daemon do sistema, defina PODSTACK_CONTROL_SOCKET:
PODSTACK_CONTROL_SOCKET=/tmp/podstack-dev.sock PODSTACK_SKIP_BUILD=1 ./scripts/dev.shO scripts/dev.sh não instala o podstack-helper, que é um serviço root. Para testar
ações do setup que instalam/removem pacotes (Podman, QEMU, Caddy etc.) em desenvolvimento:
./scripts/dev-helper.sh # instala/reinicia o helper (pede confirmação e usa sudo)
./scripts/dev-helper.sh --yes # sem confirmação
./scripts/dev-helper.sh --uninstallAtivar o podman.socket não exige o helper. Detalhes em
docs/engineering/packaging.md §4.1.
A engine é o Podman (Libpod REST). O docker-compose é usado apenas como provider do
Compose, apontando para o socket do Podman via DOCKER_HOST
(unix://$XDG_RUNTIME_DIR/podman/podman.sock), conforme o
ADR-0007. O podman-compose é um fallback com semântica
parcial; o provider padrão continua sendo o Docker Compose. Quando disponível, podman compose
pode ser usado como wrapper — ele delega ao provider.
O CLI também pode ser usado separadamente:
./build/dev/podstackd & # daemon
./build/dev/podstack status
./build/dev/podstack ps --all
./build/dev/podstack exec <container> -- /bin/echo helloLeia AGENTS.md antes de contribuir. Ele define ordem de leitura, regras de clean-room, convenções de código, fluxo de tarefas e critérios de verificação.
GPL-3.0-or-later — texto completo em LICENSE e aviso em NOTICE.
Copyright (C) 2026 PodStack contributors.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A documentação e os assets também são licenciados sob GPL-3.0-or-later, salvo indicação em contrário. O terminal embutido usa QTermWidget (GPL-2.0-or-later, compatível com GPL-3.0-or-later).
O PodStack é inspirado no fluxo de trabalho e na organização visual do OrbStack, sem reutilizar seu código, assets ou marca. OrbStack é marca da Orbital Labs; PodStack é um projeto independente.