OpenAdapt Desktop

Lifecycle: Experimental supporting surface. OpenAdapt Desktop is the local authoring and teaching cockpit for OpenAdapt. The canonical compiler and governed runtime live in openadapt-flow. This repository builds unsigned or ad-hoc-signed Experimental prereleases; it is not yet a signed, generally available desktop product.

What OpenAdapt is

OpenAdapt is a governed demonstration compiler. You record a workflow once, it compiles the demonstration into a deterministic program, and it replays that program with zero model calls on the healthy path. When an interface drifts, OpenAdapt re-resolves from retained evidence or proposes a governed repair, and it halts instead of guessing when verification fails.

Substrates are all first-class in the product design (web, Windows, macOS, Linux, RDP, and Citrix/VDI), reported against an honest maturity ladder:

Substrate	Maturity
Browser	Beta - proven end to end today; the only substrate that runs the full loop in CI
Windows, macOS, RDP	Early access - each passed a real scoped qualification on named tasks with zero silent-incorrect actions, zero over-halt, and zero model calls; no external customer has run them in production
Citrix / VDI	Exploratory - no validated ICA/HDX integration exists yet

The compiler, replayer, certification, and governed repair all live in openadapt-flow. This desktop repository is the cockpit and the local wiring around that engine, not a second copy of it.

What this repository is

OpenAdapt Desktop is two cooperating processes:

• A Tauri/React cockpit (the shell and UI).
• A Python engine sidecar it drives over a JSON-lines stdin/stdout IPC.

The engine owns consent, operating-system permissions, recording and review, hosted authentication and push, and a FlowBridge that shells out to openadapt-flow for compile, replay, run, and teach. The shell also runs a token-authenticated loopback socket server so the separately developed openadapt-tray companion can mirror status and send local commands.

It is integrated but Experimental: end-to-end tests mock the capture and flow boundaries, the frozen sidecar binary is produced only by CI, and no supported signed release exists yet.

The cockpit

Once you sign in, the shell renders a left-rail cockpit over the live engine:

Screen	What it does
Login	Sign in with a system-browser PKCE flow or by pasting an ingest token minted in the cloud dashboard; one credential is stored in the OS keychain
Onboarding	First-run guidance until a workflow exists locally
Workflows	The workflow library: recorded and compiled workflows, with their status
Record & review	Start/stop a capture and step through the local review gate before anything leaves the machine
Runner (watch it run)	Trigger a replay and watch the compile/replay rail, the live step log, and halt evidence when the run stops for attention
Teach	Resolve a halted step and write a governed repair back toward the workflow
Settings	Host, deployment lane, credentials, and local preferences

The rail carries two orthogonal status channels (recording and sync) plus the needs-attention break count, mirrored from the engine over events. In a plain dev checkout the shell renders an engine-offline state, because the frozen sidecar binary is built only in CI.

Status

Area	Checked-out implementation	Status
Python capture CLI	Record, list, inspect, scrub, review, approve, local storage, health, and cleanup commands	Experimental; covered by tests
Local review gate	Persisted states and egress checks for the capture pipeline	Experimental; not the openadapt-flow certification system
Tauri/React cockpit	Login, onboarding, workflows, record/review, watch-run, teach, and settings calling the engine through Tauri commands	Experimental; renders an engine-offline state when the sidecar binary is absent
Rust commands	Generic engine_invoke bridge plus typed commands, sidecar spawn/watchdog/shutdown, and event re-emission to the WebView	Experimental; compiled and bundled in CI
Python sidecar IPC	JSON-lines handler backed by a shared EngineDispatcher (recording, compile/replay/run/teach, auth, sync/push, review, config)	Experimental; unit and e2e tests with mocked boundaries
Tray IPC socket server	Token-authenticated loopback TCP server plus a ~/.openadapt/desktop_ipc.json discovery file for openadapt-tray	Experimental; not yet validated end to end against the shipped tray
Desktop-to-flow handoff	FlowBridge shells out to the openadapt-flow CLI for compile, replay, run, and teach	Experimental; requires a separately installed openadapt-flow on PATH (not bundled)
Hosted auth and push	Browser-PKCE and paste-token sign-in, keychain-stored credential, bundle push, and halted-run break reports to the hosted control plane	Experimental
Build artifacts	Wheel/sdist, a PyInstaller sidecar, and Experimental DMG/MSI/NSIS/DEB/AppImage native jobs	Native jobs structurally install/uninstall and label every platform, architecture, and signing state
Native installers	Distinct desktop-v* draft-prerelease workflow with final-byte checksums and GitHub provenance, auto-triggered at each engine release	Experimental packaging evidence only; unsigned or ad-hoc-signed
Code signing and updater	Apple Developer ID/notarization and Windows Authenticode are credential-gated and fail closed on partial configuration; the updater feed is disabled	In progress; not a supported release channel

The PyInstaller openadapt-engine freeze and external code signing are the two remaining pieces before an integrated, signed desktop release. They are in progress; do not read a native prerelease as a shipping signed installer.

Use OpenAdapt today

For the runnable product loop, use openadapt-flow directly:

pip install openadapt-flow

openadapt-flow demo-record --out rec
openadapt-flow compile rec --out bundle --name my-task
openadapt-flow lint bundle                                # expected to find demo gaps
openadapt-flow certify bundle --policy permissive        # smoke-policy pass
openadapt-flow certify bundle --policy clinical-write    # expected strict refusal
openadapt-flow replay bundle
openadapt-flow replay bundle --drift theme --save-healed-to healed

The bundled tutorial is runnable but intentionally not certified for clinical writes. A nonzero strict-certification result is the expected refusal boundary, not a setup failure.

Build and run this repository

Engine and cockpit from source

The Python engine and its CLI run from a plain checkout. Compile, replay, run, and teach delegate to a separately installed openadapt-flow.

git clone https://github.com/OpenAdaptAI/openadapt-desktop.git
cd openadapt-desktop
uv sync --extra dev

uv run openadapt-desktop doctor
uv run openadapt-desktop list
uv run openadapt-desktop storage

uv run pytest tests -q
uv run ruff check engine tests

Recording requires the operating-system permissions and runtime support used by openadapt-capture:

uv run openadapt-desktop record --task "Inspect capture path"

To work on the shell and frontend you also need Rust, Node.js, and the Tauri CLI. A dev shell runs frontend-only and shows the engine as offline until a frozen sidecar binary from CI is present.

Experimental native installers

Native packages are published under a distinct desktop-vX.Y.Z prerelease channel, separate from the engine's vX.Y.Z PyPI/GitHub releases. The native version is synchronized to each engine release by CI, so a native prerelease mirrors the engine version it was built from. A native prerelease is packaging evidence, and it is not a separate supported desktop release. They are unsigned or ad-hoc-signed Experimental artifacts: their filenames carry the platform, architecture, and signing state, and CI installs, launches, and uninstalls each one on clean runners. Packaging structure is not workflow qualification.

• Which release to download, and the two-lane policy, are in RELEASES.md.
• Artifact names, verification scope, and provenance are in Experimental Native Installers.
• The signing activation runbook (what to buy, which secrets to add, and what each surface may then truthfully claim) is in docs/CODE_SIGNING.md.

Do not treat the legacy upload command or optional upload extras as the supported hosted path; they predate the current workflow-bundle and break-report contract.

Architecture

The boundary is deliberately narrow:

Desktop authoring/teaching cockpit (Tauri + React)
        |
        | local IPC (JSON lines over sidecar stdio; token-authenticated
        | loopback socket for the tray)
        v
Python engine sidecar (capture, review, auth, sync, FlowBridge)
        |
        | openadapt-flow CLI on PATH
        v
openadapt-flow
  record -> compile -> lint/certify -> replay -> halt/repair/teach
        |
        +-> optional hosted control-plane metadata and break reporting

The desktop application owns consent, operating-system permissions, recording controls, inspection, and human teaching. It does not duplicate the workflow compiler or runtime. Those remain in openadapt-flow.

Known gaps

• openadapt-flow is not bundled with the frozen sidecar. Compile, replay, run, and teach require a separately installed openadapt-flow on PATH and fail with an explicit error without it.
• End-to-end tests mock the capture and flow boundaries. No CI job drives the built UI against a real engine performing a real record -> compile -> replay -> teach loop, so integration is code-complete but not product-validated.
• The frozen openadapt-engine sidecar binary is produced only by CI. A plain dev checkout runs the shell in frontend-only mode.
• Native packages are Experimental and unsigned or ad-hoc-signed; structural install/uninstall success is not evidence of a validated workflow.
• Apple Developer ID/notarization and Windows Authenticode are credential-gated and fail closed on partial configuration; the updater and rollback remain disabled pending an independent signing-key lifecycle.
• This repository serves the tray's loopback IPC contract, but the desktop and the shipped tray client have not been validated together end to end.

CLI surface

The Python engine exposes these Experimental commands:

Command	Purpose
openadapt-desktop record	Capture a local session
openadapt-desktop list / info	Inspect capture metadata
openadapt-desktop scrub	Run configured PII scrubbing
openadapt-desktop review / approve / dismiss	Operate the local review state machine
openadapt-desktop compile / replay / run	Invoke a separately installed openadapt-flow on a capture or bundle
openadapt-desktop login / push / report-break	Authenticate to the hosted control plane, push a bundle, report a halted run
openadapt-desktop storage / health / cleanup	Inspect and maintain local storage
openadapt-desktop backends / upload	Inspect or invoke legacy upload adapters
openadapt-desktop config / doctor	Inspect local configuration and dependencies

Raw recordings are local by default. Any egress path still requires careful review of the selected adapter, configuration, logs, and data-classification policy. This repository does not by itself establish a HIPAA-compliant or production-safe deployment.

Development

Prerequisites are Python 3.11+ and uv. The main implementation areas are:

engine/       Python capture, review, auth, sync, and FlowBridge code
src-tauri/    Rust/Tauri shell, sidecar lifecycle, and tray socket wiring
src/          React cockpit (screens, engine client, primitives)
tests/        Python unit and end-to-end tests, largely with mocked boundaries

See DESIGN.md as a historical design reference. Where it conflicts with this status section or with openadapt-flow, this README describes the current public product boundary.

Related projects

Project	Lifecycle and role
openadapt-flow	Canonical workflow compiler, runtime, certification, and governed repair engine
OpenAdapt	Flagship launcher and meta-repository
openadapt-tray	Experimental system-tray status and launcher companion for this cockpit
openadapt-capture	Experimental capture component used by this Python engine
openadapt-privacy	Experimental PII detection and redaction component

Documentation for the wider stack lives at docs.openadapt.ai.

License

MIT. See LICENSE.