Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 21 additions & 13 deletions docs/concepts/deployment-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,23 @@ schema. What differs across lanes is data handling, not substrate capability.

| Deployment / substrate | Browser | Windows UIA | Native macOS | RDP | Citrix / VDI |
|---|---|---|---|---|---|
| **OpenAdapt Hosted** | Managed execution, schedules, reports, usage, and billing | Managed, workflow-qualified deployment | Managed, workflow-qualified deployment | Managed, workflow-qualified deployment | Managed, workflow-qualified deployment |
| **OpenAdapt Hosted** | Managed execution, schedules, reports, usage, and billing | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary |
| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage |
| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail |

Every substrate is a first-class execution target across all three lanes. The
public $500/month self-serve subscription covers approved browser workflows.
Windows, native macOS, RDP, Citrix/VDI, regulated customer-controlled execution,
and support or assurance commitments are a separate order with per-workflow
qualification: a commercial and onboarding distinction, not a capability one. The
matrix describes the product architecture; the
Every substrate is a first-class target of the shared compiler, runner, and
safety gates. Where each lane is available today differs, and the matrix states
that plainly rather than implying uniform hosted availability. The public
$500/month self-serve subscription runs the browser substrate in OpenAdapt's
cloud. Windows, native macOS, RDP, and Citrix/VDI run in the customer boundary:
self-hosted or on-prem today, and control-plane-managed in the customer's own
cloud (BYOC) as that Experimental lane opens. An in-our-cloud desktop runner
exists only as an internal, licensing-gated lane, and multi-tenant hosting of the
desktop substrate in OpenAdapt's cloud is deferred; neither is part of any public
offer. Between the customer-boundary lanes the difference is a per-workflow
qualified commercial order rather than a capability gap, and none of these
substrates is an entitlement of the browser subscription. The matrix describes
the product architecture; the
[qualification appendix](../get-started/what-works-today.md) and commercial terms
define the accepted workload and entitlement.

Expand Down Expand Up @@ -155,12 +162,13 @@ qualified in its real environment. The published qualification evidence to date:
0 over-halts, and 0 model calls. Exact snapshot cleanup passed. Review
[Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142)
and the [immutable sanitized report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json).
- **Citrix / VDI:** Driven pixel-first through the same remote-display adapter
and the same identity gate and effect verification as every other substrate.
Each Citrix/VDI workflow is qualified in its real ICA/HDX environment: the
client, latency, compression, DPI, lock-screen, and synthetic-input behavior
are exercised against the actual application, the same real-environment
qualification step every substrate goes through.
- **Citrix / VDI (Exploratory):** Driven pixel-first through the same
remote-display adapter and the same identity gate and effect verification as
every other substrate. No real ICA/HDX environment has been qualified yet. Each
Citrix/VDI workflow must be qualified in its real ICA/HDX environment before
consequential use: the client, latency, compression, DPI, lock-screen, and
synthetic-input behavior are exercised against the actual application, the same
real-environment qualification step every substrate goes through.

Review [Qualification evidence](../get-started/what-works-today.md) and the engine's
[published limits](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/LIMITS.md)
Expand Down
28 changes: 19 additions & 9 deletions docs/concepts/substrate-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,19 @@ Two backends cover it behind the same protocol:
behavior is detailed in
[LIMITS](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/LIMITS.md).

## How the desktop substrate is hosted

When the desktop runner executes in our infrastructure (rather than inside a
customer's perimeter), the Windows surface is a **QEMU/KVM guest on a Linux
host**, streamed for
## Where the desktop substrate runs today

Today the desktop and Citrix substrates run **inside the customer boundary**:
self-hosted or on-prem on a machine the customer controls (see
[Deploy on-prem](../guides/deploy-on-prem.md)), and, as that lane opens,
control-plane-managed in the customer's own cloud (BYOC). The public managed
subscription runs the browser substrate only. The desktop mechanism, backends,
and safety gates are the same wherever they run; what differs is who owns the
machine and the data.

OpenAdapt also runs the desktop substrate in its own infrastructure as an
**internal, licensing-gated lane** rather than a public offer. There the Windows
surface is a **QEMU/KVM guest on a Linux host**, streamed for
monitoring/recording over **RDP through Apache Guacamole**. RDP is Windows-native,
so nothing streaming-related runs inside the guest and the VM stays clean for
snapshot-revert between runs. The deterministic replay path itself drives the
Expand All @@ -91,8 +99,9 @@ guest through the in-session agent contract, not the stream.
Desktop execution is provisioned per qualified workflow, so Windows licensing,
warm-state policy, isolation, recovery, and cost are explicit deployment inputs
rather than hidden properties of the runner. The same job and report contract
also supports a customer-owned Windows session when data must remain inside the
customer boundary.
drives a customer-owned Windows session unchanged. Multi-tenant hosting of the
desktop substrate in OpenAdapt's cloud is deferred; it is not part of any public
offer.

## Qualification record

Expand All @@ -117,8 +126,9 @@ customer boundary.
Exact snapshot cleanup passed. Review the
[immutable sanitized report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json).
- Citrix/VDI is driven pixel-first through the same identity gate and effect
verification as every substrate, and each workflow is qualified in its real
ICA/HDX environment.
verification as every substrate. No real ICA/HDX environment has been qualified
yet (status: Exploratory); each workflow must be qualified in its real ICA/HDX
environment before consequential use.
- The public hosted subscription currently entitles approved browser workflows.
Desktop and virtual-desktop deployments are scoped and qualified separately.

Expand Down
14 changes: 9 additions & 5 deletions docs/get-started/what-works-today.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,12 @@ execution, usage, portal, and cancellation as continuing production evidence.

## How to read this appendix

Every surface below is **Supported**: a first-class product surface you can build
on, backed by the evidence in the "What is actually demonstrated" column. The
Most surfaces below are **Supported**: a first-class product surface you can build
on, backed by the evidence in the "What is actually demonstrated" column. A few
carry a narrower status the Status column names explicitly: **Supported / scoped
deployment** (qualified and ordered as a scoped deployment), **Experimental** or
**Internal only** (built but not a public offer), and **Exploratory** (the
mechanism exists but no real environment has been qualified yet). The
"Important boundary" column states, honestly and per surface, exactly what each
result does and does not cover. Read it before trusting a surface with
consequential work. Public delivery of a given surface may still carry a separate
Expand Down Expand Up @@ -52,7 +56,7 @@ through before it carries consequential work.
| Windows UIA backend | **Supported / scoped deployment** | The counted `20260717-candidate-56759c8-v2` in-tree WinForms matrix completed 3/3 trials; an independent SQLite oracle confirmed 3/3 effects; stale-target and ambiguous-target controls each refused 3/3; there were 0 silent incorrect successes, 0 over-halts, and 0 model calls. [Review the immutable report at the merged Flow commit](https://github.com/OpenAdaptAI/openadapt-flow/blob/defafbae758a75c8e149d9693f2cffe1f2264b8c/benchmark/windows_uia/results.json) and [Flow PR #132](https://github.com/OpenAdaptAI/openadapt-flow/pull/132). | The report also preserves earlier rejected diagnostic runs; their failures are not counted acceptance trials. Each Windows workflow is qualified in its real environment; the published evidence covers the named workflow and Windows 11 ARM VM snapshot. |
| Native macOS backend | **Supported / scoped deployment** | On one macOS 15.7.3 arm64 host, candidate `b1b61a5` completed 3/3 exact-byte TextEdit trials and refused a two-window ambiguity without changing either file; there were 0 silent incorrect successes and 0 over-halts. [Review the hash-bound adjudication at immutable evidence commit `ca1b522`](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json) and [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135). | The counted candidate is `b1b61a5`; `ca1b522` preserves its reports and adjudication but is not the current PR head. The immutable original report remains `status: failed` because graceful-close cleanup warnings were classified as batch failure. The separate adjudication preserves that result, verifies the exact harness PIDs and temporary root were absent, and accepts the action-effect and ambiguity-refusal evidence. Each macOS workflow is qualified in its real environment. |
| RDP backend | **Supported / scoped deployment** | On one Parallels Windows 11 VM at 1280x800 with Aardwolf 0.2.14, candidate `82a658a` completed 3/3 trials that created a unique file through the Windows Run dialog over network RDP. Independent guest-tools readback confirmed the exact file contents. Trial latencies were 51.845s, 10.467s, and 7.477s; there were 0 failures, 0 silent incorrect successes, 0 over-halts, and 0 model calls. [Review the immutable sanitized report at evidence commit `6610d24`](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json) and [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142). | Cleanup deleted only the batch-owned snapshot, restored the exact eight-snapshot inventory, left the VM suspended, and returned the current pointer without resume to the unchanged original base. Each RDP workflow is qualified in its real environment; the published evidence covers the named task, VM snapshot, transport, and oracle. Earlier rejected batches remain evidence and are not counted as acceptance trials. |
| Citrix / VDI backend | **Supported / scoped deployment** | Driven pixel-first through the same remote-display adapter, identity gate, and effect verification as every substrate. | Each Citrix/VDI workflow is qualified in its real ICA/HDX environment, where the client, latency, compression, DPI, lock-screen, input, identity, and effect behavior are exercised against the actual application. |
| Citrix / VDI backend | **Exploratory** | The pixel-first mechanism (the same remote-display adapter, identity gate, and effect verification as every substrate) is implemented, but no real Citrix ICA/HDX environment has been qualified yet. | Each Citrix/VDI workflow must be qualified in its real ICA/HDX environment, where the client, latency, compression, DPI, lock-screen, input, identity, and effect behavior are exercised against the actual application, before it carries consequential work. |
| Desktop authoring GUI and tray | **Supported** | The published 0.1.1 prerelease provides install/uninstall-qualified native packages across the six targeted platform/architecture variants. | The current prerelease qualifies packaging and removal; the complete record -> compile -> replay -> teach cockpit remains an integration track. |
| Hosted CLI connectivity | **Supported / public offer** | `login`, exact-hash artifact preparation/upload, one-time runtime validation, bound replacement activation, and `report-break` connect the local engine to the live control plane. | Upload requires destination policy and an approved sanitized derivative; checkout never bypasses an egress refusal. |
| Artifact sanitation and local review | **Supported / launch gate** | The sanitized-derivative pipeline inventories, transforms, rescans, manifests, hashes, and supports local review/approval. | The raw original remains sensitive; unknown or unresolved content is refused; runtime observations can reintroduce PHI. |
Expand All @@ -61,8 +65,8 @@ through before it carries consequential work.
| Hosted dashboard/control plane | **Supported / public offer** | Authentication, organizations, exact-hash bundle ingest, immutable run admission, browser runner orchestration, structural reports, replacement activation, billing, and metering form the managed lifecycle. | Production uses live dependencies and fails unavailable rather than substituting mock behavior. |
| Hosted execution | **Supported / public offer** | Live Stripe Checkout connects onboarding and subscription entitlements to managed browser execution; the runner verifies exact admitted bundle bytes and authenticated callbacks. | The public subscription covers approved browser workflows. Other substrates use separately scoped deployments and commercial terms. Checkout does not create an SLA or certification. |
| Air-gapped on-prem package | **Supported** | A local queue, systemd unit, minimized hash-chained audit log, and air-gap checks are provided. | Full-disk encryption and operational hardening remain operator/deployment responsibilities. |
| BYOC / customer-controlled execution | **Supported / scoped deployment** | A connector and customer-storage contract support keeping the data plane inside an approved customer boundary. | Qualify the actual substrate and destination; PHI-bearing runtime data must not cross into a shared boundary. |
| Hosted desktop runner | **Supported** | A Windows runner contract and implementation path exist. | Desktop subscriptions and deployments are scoped separately from the public browser offer and qualified per workflow. |
| Control-plane-managed customer cloud (BYOC) | **Experimental** | An outbound-connector pull queue, per-connector authentication, and a customer-owned storage handoff are implemented, but the lane is disabled on the live hosted path and no connector transport ships in the engine yet. | Qualify the actual substrate and destination; PHI-bearing runtime data must not cross into a shared boundary. |
| Hosted desktop runner (in OpenAdapt's cloud) | **Internal only** | A Windows-in-cloud runner and its enqueue/callback contract are implemented, but the lane is licensing-gated and a fail-closed flag restricts it to an internal allowlist. | This lane is not part of any public commercial offer. Hosted in-our-cloud desktop, RDP, and Citrix execution is not sold today; those substrates run self-hosted or on-prem in the customer boundary, with control-plane-managed BYOC as an Experimental lane, and are scoped separately from the public browser offer and qualified per workflow. Multi-tenant hosting of the desktop substrate in OpenAdapt's cloud is deferred. |

## Before using consequential data

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/hosted.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ price you pay at Checkout.
| Windows UIA | **Supported / scoped deployment** | The exact in-tree WinForms matrix passed 3/3 with an independent SQLite oracle and 3/3 stale/ambiguity refusals. Windows subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. |
| Native macOS | **Supported / scoped deployment** | One macOS 15.7.3 arm64 host produced 3/3 exact-byte TextEdit effects plus a two-window ambiguity refusal. Native macOS subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. |
| RDP | **Supported / scoped deployment** | One Parallels Windows 11 VM produced 3/3 exact guest-file effects through network RDP, with 0 silent incorrect successes, 0 over-halts, and 0 model calls. RDP subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. |
| Citrix / VDI | **Supported / scoped deployment** | Driven pixel-first through the same identity gate and effect verification as every substrate; ordered separately from the public browser offer and qualified in its real ICA/HDX environment per workflow. |
| Citrix / VDI | **Exploratory** | The pixel-first mechanism shares the same identity gate and effect verification as every substrate, but no real ICA/HDX environment has been qualified yet; ordered separately from the public browser offer and qualified in its real ICA/HDX environment per workflow before consequential use. |
| Regulated runtime data | **Customer-controlled boundary** | Use a scoped BYOC/on-prem deployment when live screens necessarily contain PHI. |

The public subscription covers approved browser workflows. Windows, native
Expand Down
6 changes: 4 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Two orthogonal axes, one contract:

| Deployment ↓ / Substrate → | **Web (browser)** | **Windows UIA** | **Native macOS** | **RDP** | **Citrix** |
|---|---|---|---|---|---|
| **OpenAdapt Cloud** | Managed runner, schedules, reports, usage, and billing | Separately ordered, workflow-qualified deployment | Separately ordered, workflow-qualified deployment | Separately ordered, workflow-qualified deployment | Separately ordered design-partner deployment |
| **OpenAdapt Cloud** | Managed runner, schedules, reports, usage, and billing | Not multi-tenant hosted; runs in the customer boundary | Not multi-tenant hosted; runs in the customer boundary | Not multi-tenant hosted; runs in the customer boundary | Design-partner; runs in the customer boundary |
| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage |
| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail |

Expand All @@ -135,7 +135,9 @@ it gates certification, identity and effect coverage, approval fallback,
encryption, and manifest integrity before execution.

The public subscription covers approved browser workflows. Desktop and
virtual-desktop lanes require a separate order and workflow-specific
virtual-desktop lanes run in the customer boundary (self-hosted or on-prem today,
control-plane-managed BYOC as that Experimental lane opens), not in OpenAdapt's
multi-tenant cloud, and they require a separate order and workflow-specific
qualification; they are not entitlements of the browser subscription. The
[hosted guide](guides/hosted.md),
[qualification evidence](get-started/what-works-today.md), and commercial terms
Expand Down
Loading