Omnideck Desktop — a native app for managing your Omnideck agent workspaces.

---

A Tauri v2 + React/TypeScript desktop app that manages one or more local Omnideck instances ("Decks") — start/stop/update/remove, live status, logs — and drives first-run setup of the Podman runtime they need. It's a thin GUI shell: almost no container logic lives here, it's a front end over the omnideck CLI.

Architecture

┌──────────────────────┐        ┌──────────────────────────┐
│   "main" (dashboard)  │        │   "onboarding" (hidden    │
│                       │        │    until actually needed) │
│   React + TypeScript  │        │   vanilla JS/HTML/CSS     │
│   Deck list, start/   │        │   first-run/repair Podman │
│   stop/update/remove  │        │   runtime setup           │
└───────────┬───────────┘        └────────────┬──────────────┘
            │                                 │
            └───────────────┬─────────────────┘
                             ▼
              src-tauri/src/cli_bridge.rs
        (owns all `omnideck` CLI subprocess I/O —
         spawn, JSON/NDJSON parsing, bounds, timeouts)
                             │
                             ▼
              bundled `omnideck` CLI sidecar
           (pinned by version + checksum, never PATH)

Two windows, two frontend stacks, deliberately — the dashboard is React with a broad command surface; onboarding is an isolated, minimally-privileged vanilla-JS window with its own Tauri capability, unreachable from the dashboard. (This repo briefly went single-window mid-development, suspecting the two-window pattern caused a real EGL_BAD_PARAMETER crash on some Linux hardware — it didn't; the actual cause was a CI build-environment mismatch, see AGENT.md's postmortem section. Once confirmed, the two-window design came back.) See src-tauri/src/bootstrap.rs's module doc comment for the full rationale, and reference/desktop-hardening-migration-PLAN.md for how this repo's security posture got here.

Commands

Command	What it does
npm install	Install frontend dependencies
npm run fetch:sidecars	Download + checksum-verify the pinned omnideck CLI binaries (once per checkout)
npm run dev:app	Run the full app — Vite + Rust backend, hot reload
npm run dev	Frontend only, no Rust/webview (fast React/CSS iteration)
npm run build	Typecheck + production frontend bundle
npm run verify	The full local gate: sidecars, policy tests, typecheck, cargo fmt/test/clippy — what CI runs
npm run test:policy	Security-posture assertions (capabilities, sidecar pin, process hardening)

See DEVELOPMENT.md for the rest (platform-specific builds, backend-only commands, onboarding-flow testing) and RELEASING.md for cutting a release.

Getting started

Requires Node.js 18+, Rust (stable), and the Tauri v2 platform build tools (prerequisites). Linux on an immutable/atomic distro (Fedora Silverblue, Bluefin, etc.) needs one extra setup step — see DEVELOPMENT.md.

git clone https://github.com/omnideck-dev/desktop
cd desktop
npm install
npm run fetch:sidecars
npm run dev:app

The dashboard window opens immediately. If you don't have a ready Podman runtime yet, an onboarding window guides you through setting one up.

Documentation

• DEVELOPMENT.md — full dev environment setup, testing (including previewing onboarding screens without touching real Podman state), and the command reference
• TESTING.md — the full test-layer breakdown (source, release contract, native smoke, manual) and what's deliberately not built yet
• RELEASING.md — tagging, the CI release pipeline, and the review-gate policy
• AGENT.md — architecture, non-negotiable rules, and current build status (the primary reference for contributing code)
• DESIGN.md — screen-by-screen UI/UX reference
• reference/ — the specs and migration plans this app was built from

Roadmap

See the public Omnideck Roadmap board for what's planned, in progress, and recently shipped.

Contributing

Issues and PRs welcome. Start with AGENT.md for the architecture and the rules that keep this app's security posture intact (capability scoping, CLI sidecar pinning, the CLI-delegated multi-instance model), then DEVELOPMENT.md to get a dev environment running. npm run verify is the same gate CI runs — get it green locally before opening a PR.