Skip to content

Connect the desktop app to a cloud workspace

The local loop — record, compile, replay, teach — works entirely offline and needs no account. Connecting to a cloud workspace (app.openadapt.ai) adds an org-wide dashboard where pushed workflows are visible and runs that need attention are triaged. This page walks the whole path: sign in → mint an ingest token → connect the desktop app → push your first recording → see it in the dashboard.

Which lane are you in?

The cloud workspace is the self-serve, non-PHI lane — browser/web automation that does not carry regulated data. If you handle PHI or other regulated data, do not push to the cloud; use the on-prem deployment instead, where recordings and teaching never leave your network. See the hosted option.

Early access

The self-serve cloud runner is being rolled out with early-access users and is not yet a public paid tier. Request access from openadapt.ai. The steps below are the mechanism the desktop app and CLI use once your workspace is enabled.

1. Create or sign in to your workspace

Sign in at app.openadapt.ai (Google or magic-link). Your account resolves to exactly one organization — every token and workflow belongs to that org.

2. Mint an ingest token

The desktop app authenticates to the cloud with a per-user ingest token (oai_ingest_…). To mint one:

  1. In the dashboard, open Settings → Ingest tokens (app.openadapt.ai/dashboard/settings/ingest).
  2. Click Create token and give it a name (e.g. your machine name).
  3. Copy the token now. It is shown once and stored server-side only as a hash — if you lose it, revoke it and mint a new one.

The token is presented as Authorization: Bearer <token> on every call and resolves to your org. Revoke it any time from the same page.

3. Connect the desktop app

Desktop login is landing; the CLI path works today

The login flow below describes the desktop cockpit that is currently rolling out (the published installers are an experimental preview). Until your build includes it, use the CLI commands shown alongside each step — they are the same mechanism.

In the desktop app, open Login and either:

  • Click Login — opens app.openadapt.ai in your system browser and completes sign-in there (Google / magic-link "just work"), or
  • Paste a token — paste the oai_ingest_… token from step 2.

Either way the credential is stored in your OS secure store (macOS Keychain / Windows Credential Manager / Linux Secret Service), not in a plaintext file.

Prefer the CLI? The same thing from a terminal:

openadapt flow login --token oai_ingest_…      # validates + remembers the host

login resolves the token from --token, then the OPENADAPT_INGEST_TOKEN environment variable, then ~/.openadapt/config.toml. See the CLI reference.

4. Push your first recording

Record a workflow (see Record your own app), then push it. From the desktop app, use Push to cloud on the recording (where your build includes it). From the CLI:

openadapt flow push ./my-recording --name "Triage"
#   → zips the recording, POSTs it to /api/ingest,
#     compiles it in the cloud, and prints a workflow id + dashboard URL

A recording directory is zipped before upload (the server ingests a .zip; the engine emits a directory). You can also push an already-compiled bundle with --kind bundle. See push.

Push scrubs, but the cloud lane is for non-PHI work

A pre-push scrub runs fail-closed and the server re-scans on ingest, but the cloud lane is not the PHI lane. Keep regulated recordings local and use on-prem.

5. See it in the dashboard

Open the dashboard URL that push printed (or go to app.openadapt.ai/dashboard/workflows). The pushed workflow appears there, compiled and runnable, and any run that halts and needs attention surfaces under Needs attention for triage.

Reporting a halt back to the workspace

When a governed run halts locally, you can send a PHI-free break descriptor to the workspace so the halt is visible centrally, without the recording ever leaving the machine:

openadapt flow report-break runs/replay-… \
    --workflow-id <id> --deployment-kind byoc

report-break reads the halt from the run's report.json, scrubs it fail-closed, and posts only a descriptor. See report-break and the halt-learn loop for how a halt becomes a taught correction.