Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(cua-driver): publish SDK guides and architecture (#2499)

Francesco Bonacci63049ff598ce
diff --git a/docs/README.md b/docs/README.md
index bf6d7a6821..70e45c05aa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,7 +18,8 @@ Public docs live in `content/docs/` and follow the Diátaxis modes:
- `tutorials/` teach a guided first success.
- `how-to-guides/` give steps for a specific goal.
-- `explanation/` explains concepts, constraints, and tradeoffs.
+- `concepts/` contains Diátaxis explanations of concepts, constraints, and
+ tradeoffs.
- `reference/` is dry lookup: commands, APIs, contracts, limits.
Place content by what the reader is trying to do, not by topic. Do not mix modes in one page; move reference tables to reference pages and link to them from how-to guides or explanations.
diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.json
index 5315c515fc..3f8d28bbdb 100644
--- a/docs/content/docs/concepts/meta.json
+++ b/docs/content/docs/concepts/meta.json
@@ -4,6 +4,7 @@
"pages": [
"index",
"what-is-computer-use",
+ "sdk-mcp-and-hosting",
"the-no-foreground-contract",
"capture-and-delivery-modalities",
"browser-targeting-and-background-delivery",
diff --git a/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx b/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx
new file mode 100644
index 0000000000..135fc6b1fb
--- /dev/null
+++ b/docs/content/docs/concepts/sdk-mcp-and-hosting.mdx
@@ -0,0 +1,78 @@
+---
+title: 'SDK, MCP, and process hosting'
+description: 'How Cua Driver separates its typed application contract, agent protocol, and desktop process identity.'
+---
+
+Cua Driver has two caller interfaces and two execution topologies. They solve
+different problems:
+
+- The **SDK** is a typed application API for Python, TypeScript, and Rust.
+- **MCP** is the runtime-neutral agent protocol exposed by the Cua Driver
+ server.
+- A **same-process runtime** performs desktop work inside the importing app.
+- A **daemon runtime** performs desktop work in a long-lived process with a
+ stable operating-system identity.
+
+These dimensions form a grid, but only two cells are primary:
+
+| | Typed SDK | MCP / CLI |
+| ------------ | ----------------------------------- | ------------------------------------------------ |
+| Same process | **Primary for client applications** | Not a separate public client mode |
+| Daemon | Compatibility or app-shared runtime | **Primary for agents and short-lived CLI calls** |
+
+The SDK adds unique value in the same-process cell: typed records and direct
+calls across the generated native boundary without a socket. If application
+code talks to the same daemon as an agent, the SDK is mainly a typed
+compatibility adapter over that existing daemon.
+
+## One typed contract
+
+The public typed `CuaDriver` SDK contract is canonical:
+
+```text
+private platform implementations
+ |
+ v
+public typed CuaDriver SDK contract
+ | | |
+ v v v
+ Rust apps UniFFI MCP server adapter
+ / \ |
+ Python TypeScript agents and CLI
+```
+
+The MCP server is downstream of the same public SDK contract as an
+application. It does not maintain a second implementation of desktop tools.
+MCP remains valuable because it standardizes discovery, calls, results, tasks,
+and transport for agent runtimes; the generated language SDKs are for
+applications embedding the native runtime.
+
+## Why the daemon still exists
+
+External agents and CLI calls are short-lived or run outside the desktop app
+that owns permissions. A daemon gives them a stable execution identity,
+long-lived session state, and one controlled gateway to the physical desktop.
+
+On macOS, Accessibility and Screen Recording grants attach to an application
+identity and responsibility chain. The standalone `CuaDriver.app` daemon keeps
+that identity stable across CLI and agent reconnects. A signed app that needs
+to expose MCP can instead spawn a private daemon directly so the child reuses
+the app's TCC grants.
+
+On Windows, a daemon can remain in the logged-in interactive session while an
+SSH or service-side client cannot access that desktop. On every platform, it
+also owns cleanup for recordings, cursors, policy, and per-session state when a
+client disconnects.
+
+## Why embedded applications may choose either topology
+
+Apps such as signed Electron desktop clients may want their own permission row
+and onboarding. If only the app calls Cua Driver, `CuaDriver.create()` runs the
+runtime in that permission-owning process. If external agents must connect,
+the app can host a private daemon and publish its MCP connection. Both routes
+consume the same typed behavior; the difference is lifecycle and process
+identity, not a different action implementation.
+
+See [Process model](/reference/cua-driver/process-model) for platform details
+and [Expose MCP from a desktop app](/how-to-guides/driver/expose-mcp-from-desktop-app)
+for the hosted-daemon procedure.
diff --git a/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx b/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx
new file mode 100644
index 0000000000..96c2e574b7
--- /dev/null
+++ b/docs/content/docs/how-to-guides/driver/expose-mcp-from-desktop-app.mdx
@@ -0,0 +1,60 @@
+---
+title: 'Expose MCP from a desktop app'
+description: "Host a private Cua Driver daemon when an external agent must reuse your app's desktop permissions."
+---
+
+Use a daemon-backed host only when a signed desktop application must expose Cua
+Driver to an external MCP client. If only your application calls the driver,
+use [`CuaDriver.create()`](/how-to-guides/driver/use-sdk-in-process) instead.
+
+## Bundle the executable
+
+Ship a compatible `cua-driver` executable as an application resource. In an
+Electron app, keep it outside the ASAR archive, preserve its executable bit,
+and sign the nested executable before signing and notarizing the enclosing app.
+The npm package supplies the native SDK library but does not bundle the
+executable. The Python wheel does bundle it.
+
+## Start the host from the permission-owning process
+
+```ts
+import { CuaDriver, EmbeddedCuaDriverHost } from '@trycua/cua-driver';
+
+const host = new EmbeddedCuaDriverHost(
+ '/path/inside/YourApp.app/Contents/Resources/cua-driver',
+ 'com.example.your-app'
+);
+
+const connection = await host.start();
+const driver = CuaDriver.connect(connection.socketPath);
+
+// Application code calls the same typed SDK methods on `driver`.
+// The external agent launches `connection.mcp.command` with
+// `connection.mcp.args` and `connection.mcp.environment`.
+```
+
+On macOS, call `start()` from the app process that owns Accessibility and
+Screen Recording permission. A gateway, terminal, `open`, or `NSWorkspace`
+changes the TCC responsibility chain and cannot lend the app's grants to the
+child.
+
+## Shut down in dependency order
+
+Stop accepting new work, end active sessions, close MCP clients, then tear down
+the SDK client and host:
+
+```ts
+await driver.shutdown();
+driver.uniffiDestroy();
+await host.stop();
+host.uniffiDestroy();
+```
+
+`start()` coalesces concurrent callers. `stop()` cancels startup and is
+idempotent. After `restart()`, discard the old connection: the generation, PID,
+and endpoint change. Use `waitForExit(connection.generation)` to observe an
+unexpected child exit, and never automatically replay an action whose outcome
+is unknown.
+
+For the complete lifecycle and low-level launch contract, see
+[Embedding reference](/reference/cua-driver/embedding).
diff --git a/docs/content/docs/how-to-guides/driver/keep-running.mdx b/docs/content/docs/how-to-guides/driver/keep-running.mdx
index f8973fdbf7..863bae3aaf 100644
--- a/docs/content/docs/how-to-guides/driver/keep-running.mdx
+++ b/docs/content/docs/how-to-guides/driver/keep-running.mdx
@@ -6,7 +6,12 @@ description: Register Cua Driver as a persistent daemon that starts automaticall
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
-Cua Driver requires a daemon for tool execution. The daemon owns the per-pid element cache, permission policy, recording and configuration state, macOS TCC attribution, and the Windows interactive-session context. MCP and one-shot CLI calls fail if they cannot reach it.
+External MCP clients and one-shot CLI calls require a daemon. The daemon owns
+the per-pid element cache, permission policy, recording and configuration
+state, macOS TCC attribution, and the Windows interactive-session context. Keep
+it running when you use those interfaces. Applications that import
+`CuaDriver.create()` execute through the same-process SDK and do not need this
+setup.
<Tabs items={['macOS', 'Windows', 'Linux']}>
<Tab value="macOS">
diff --git a/docs/content/docs/how-to-guides/driver/meta.json b/docs/content/docs/how-to-guides/driver/meta.json
index dcda5a1837..a064ba96fb 100644
--- a/docs/content/docs/how-to-guides/driver/meta.json
+++ b/docs/content/docs/how-to-guides/driver/meta.json
@@ -2,6 +2,8 @@
"title": "Driver",
"pages": [
"install",
+ "use-sdk-in-process",
+ "expose-mcp-from-desktop-app",
"install-agent-skill",
"run-in-macos-lume-vm",
"run-tests-in-macos-lume-vm",
diff --git a/docs/content/docs/how-to-guides/driver/use-sdk-in-process.mdx b/docs/content/docs/how-to-guides/driver/use-sdk-in-process.mdx
new file mode 100644
index 0000000000..2585378417
--- /dev/null
+++ b/docs/content/docs/how-to-guides/driver/use-sdk-in-process.mdx
@@ -0,0 +1,124 @@
+---
+title: 'Use Cua Driver in process'
+description: 'Call the typed Cua Driver SDK directly from Python or TypeScript without a daemon.'
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+
+Use the same-process SDK when your application owns the desktop-control
+lifecycle. `CuaDriver.create()` loads the Rust runtime into the importing
+process; it does not launch `cua-driver serve` or use IPC.
+
+## Install the SDK
+
+<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+```bash
+python -m pip install cua-driver
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```bash
+npm install @trycua/cua-driver
+```
+
+ </Tab>
+</Tabs>
+
+## Start a session and capture the desktop
+
+Choose the capture scope when the session starts:
+
+- `AUTO` begins with the window-focused action ladder and permits an explicit
+ escalation to desktop tools when narrower options are exhausted.
+- `WINDOW` is strict window-only mode.
+- `DESKTOP` is strict whole-desktop mode.
+
+<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
+ <Tab value="Python">
+
+```python
+import asyncio
+
+from cua_driver import (
+ CaptureScope,
+ CuaDriver,
+ EndSessionInput,
+ GetDesktopStateInput,
+ StartSessionInput,
+)
+
+
+async def main() -> None:
+ driver = CuaDriver.create()
+ session = "desktop-capture"
+ await driver.start_session(
+ StartSessionInput(
+ session=session,
+ capture_scope=CaptureScope.DESKTOP,
+ )
+ )
+ try:
+ result = await driver.get_desktop_state(
+ GetDesktopStateInput(
+ session=session,
+ screenshot_out_file=None,
+ )
+ )
+ if result.is_error:
+ raise RuntimeError(result.text)
+ print(result.images[0].mime_type)
+ finally:
+ await driver.end_session(EndSessionInput(session=session))
+ await driver.shutdown()
+
+
+asyncio.run(main())
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```ts
+import {
+ CaptureScope,
+ CuaDriver,
+ EndSessionInput,
+ GetDesktopStateInput,
+ StartSessionInput,
+} from '@trycua/cua-driver';
+
+const driver = CuaDriver.create(undefined);
+const session = 'desktop-capture';
+
+await driver.startSession(
+ StartSessionInput.new({
+ session,
+ captureScope: CaptureScope.Desktop,
+ })
+);
+
+try {
+ const result = await driver.getDesktopState(GetDesktopStateInput.new({ session }));
+ if (result.isError) throw new Error(result.text);
+ console.log(result.images[0]?.mimeType);
+} finally {
+ await driver.endSession(EndSessionInput.new({ session }));
+ await driver.shutdown();
+ driver.uniffiDestroy();
+}
+```
+
+ </Tab>
+</Tabs>
+
+Keep one `CuaDriver` object for the application lifetime. End every session you
+start. `shutdown()` is idempotent and rejects new work after shutdown while
+allowing already-admitted operations to finish.
+
+If an external agent must also connect to your signed desktop application, use
+[Expose MCP from a desktop app](/how-to-guides/driver/expose-mcp-from-desktop-app)
+instead.
diff --git a/docs/content/docs/reference/cua-driver/embedding.mdx b/docs/content/docs/reference/cua-driver/embedding.mdx
index 28c40f902e..08b5e1b8ce 100644
--- a/docs/content/docs/reference/cua-driver/embedding.mdx
+++ b/docs/content/docs/reference/cua-driver/embedding.mdx
@@ -1,9 +1,18 @@
---
-title: Embedding
-description: Run a Cua Driver daemon as a direct child of your host app and connect an MCP proxy to it.
+title: App-hosted daemon reference
+description: Run a private Cua Driver daemon when a desktop app must expose MCP using its permission identity.
---
-Embedding runs a dedicated `cua-driver serve` daemon as a direct child of your host app instead of launching the standalone `CuaDriver.app`. On macOS, the daemon inherits the host app's Accessibility and Screen Recording grants, so users only approve your app. A second `cua-driver mcp` child proxies stdio MCP traffic to that daemon; it never executes tools itself.
+This reference describes the daemon-backed host for an application that must
+expose MCP to an external agent. It is not required for ordinary SDK use:
+[`CuaDriver.create()`](/how-to-guides/driver/use-sdk-in-process) runs the driver
+inside the importing process with no daemon or socket.
+
+The app-hosted form runs a dedicated `cua-driver serve` daemon as a direct
+child of your host app instead of launching the standalone `CuaDriver.app`. On
+macOS, the daemon inherits the host app's Accessibility and Screen Recording
+grants, so users only approve your app. A second `cua-driver mcp` child proxies
+stdio MCP traffic to that daemon; it never executes tools itself.
A complete macOS reference host and demo live in the repo at `libs/cua-driver/rust/examples/embedded-host-macos`.
diff --git a/docs/content/docs/reference/cua-driver/meta.json b/docs/content/docs/reference/cua-driver/meta.json
index 7b70992440..f7166e3f51 100644
--- a/docs/content/docs/reference/cua-driver/meta.json
+++ b/docs/content/docs/reference/cua-driver/meta.json
@@ -2,6 +2,7 @@
"title": "Cua Driver",
"pages": [
"cli-reference",
+ "sdk-reference",
"telemetry",
"macos-permissions",
"embedding",
diff --git a/docs/content/docs/reference/cua-driver/process-model.mdx b/docs/content/docs/reference/cua-driver/process-model.mdx
index 15eb76926c..aa3efc324d 100644
--- a/docs/content/docs/reference/cua-driver/process-model.mdx
+++ b/docs/content/docs/reference/cua-driver/process-model.mdx
@@ -1,13 +1,22 @@
---
title: "Process model"
-description: "How Cua Driver maps one tool surface onto CLI, MCP, and daemon-backed processes."
+description: "How Cua Driver maps one typed surface onto same-process SDK and daemon-backed execution."
---
-Cua Driver has several process shapes, but they are adapters around one driver surface: list windows, read accessibility, capture the screen, click, type, record, configure, and report state. The process model places that surface in the operating-system context that can perform it.
+Cua Driver has two execution families around one typed driver surface: list
+windows, read accessibility, capture the screen, click, type, record,
+configure, and report state.
-All Cua Driver tool execution happens in a long-lived `cua-driver serve` daemon. MCP stdio and one-shot CLI calls are client adapters: they send requests to the daemon and never execute tools locally.
+- `CuaDriver.create()` runs the Rust driver in the importing Python,
+ TypeScript, or Rust process. It requires no daemon, executable, or IPC.
+- `cua-driver serve` runs the same SDK contract in a long-lived daemon. MCP
+ stdio, one-shot CLI calls, and `CuaDriver.connect()` send requests to it.
-## Three process roles
+The MCP server is a downstream consumer of the public typed SDK contract, not a
+parallel desktop implementation. See
+[SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting).
+
+## Daemon-backed process roles
The MCP stdio proxy is *client-owned*. The parent process starts `cua-driver mcp`, keeps stdin and stdout connected, and sends MCP tool calls over that transport. The proxy forwards every call to the daemon.
@@ -15,7 +24,8 @@ The daemon shape is *machine-owned*. A single `cua-driver serve` process listens
The one-shot CLI adapter is *call-owned*. `cua-driver call <tool>` connects to the daemon, prints one result, and exits. If the daemon is unavailable, the command fails instead of executing the tool in the CLI process.
-These are transport roles around one daemon-owned implementation.
+These are transport roles around a daemon-owned instance of the same typed
+runtime that applications can create in process.
## Why a daemon proxy exists
@@ -23,18 +33,29 @@ The **daemon-proxy pattern** separates the process that speaks to the caller fro
On macOS, the root issue is **TCC**, Transparency Consent and Control. Accessibility and Screen Recording grants are attached to a specific app identity, represented by a bundle ID. Grants to `CuaDriver.app` do not automatically cover every subprocess named `cua-driver`.
-## Supported macOS launch modes
+## Supported macOS identities
-Use one of two supported daemon identities:
+macOS supports three intentional identities:
-- **Standalone:** grant permissions to the installed `CuaDriver.app` and launch its daemon through LaunchServices. See [macOS permissions](/reference/cua-driver/macos-permissions).
-- **Embedded:** have the macOS app that owns the grants spawn `cua-driver serve --embedded` directly, then connect an MCP proxy to its socket. See [Embedding](/reference/cua-driver/embedding).
+- **Same-process SDK:** import `CuaDriver.create()` in the signed app that owns
+ the grants. Desktop operations inherit that host process's identity.
+- **Standalone daemon:** grant permissions to the installed `CuaDriver.app` and
+ launch its daemon through LaunchServices. See
+ [macOS permissions](/reference/cua-driver/macos-permissions).
+- **App-hosted daemon:** have the macOS app that owns the grants spawn
+ `cua-driver serve --embedded` directly, then connect an MCP proxy to its
+ socket. See [Embedding](/reference/cua-driver/embedding).
A raw daemon launched outside `CuaDriver.app` without embedded mode has no stable TCC identity and is unsupported. Do not grant permissions to arbitrary binary paths or use that configuration in production.
If an IDE terminal starts `cua-driver` directly, macOS attributes that subprocess to the terminal app's bundle, not to `CuaDriver.app`. The binary is right, but the privacy identity is wrong.
-The daemon path fixes the attribution. The daemon is launched through LaunchServices with `open -n -g -a CuaDriver`, so macOS treats it as part of `CuaDriver.app`. The MCP stdio process remains where the assistant spawned it, but becomes a thin proxy: it forwards tool calls to the daemon over a Unix socket and returns the daemon's responses. There are two processes, but one tool surface.
+The standalone daemon path fixes attribution for external callers. It launches
+through LaunchServices with `open -n -g -a CuaDriver`, so macOS treats it as
+part of `CuaDriver.app`. The MCP stdio process remains where the assistant
+spawned it, but becomes a thin proxy: it forwards tool calls to the daemon over
+a Unix socket and returns the daemon's responses. There are two processes, but
+one tool surface.
## Windows has the same shape for a different reason
@@ -65,4 +86,9 @@ Cleanup follows the proxy connection, not a final message. The proxy keeps a lon
The proxy and one-shot CLI processes may come and go, but the daemon owns element-index caches, active recordings, configuration, policy, and cursor state. This makes the execution identity and permission-policy boundary stable across client reconnects.
-If the daemon disappears, clients fail closed. They do not construct a fresh tool registry or continue with partial state.
+If the daemon disappears, daemon-backed clients fail closed. They do not
+construct a fresh tool registry or continue with partial state.
+
+For a same-process SDK runtime, the importing application owns the equivalent
+lifetime. End every session, await `shutdown()`, and release the generated
+binding handle during orderly teardown.
diff --git a/docs/content/docs/reference/cua-driver/sdk-reference.mdx b/docs/content/docs/reference/cua-driver/sdk-reference.mdx
new file mode 100644
index 0000000000..7056c75bd8
--- /dev/null
+++ b/docs/content/docs/reference/cua-driver/sdk-reference.mdx
@@ -0,0 +1,107 @@
+---
+title: 'SDK reference'
+description: 'Python and TypeScript packages, constructors, methods, results, and errors for the typed Cua Driver SDK.'
+---
+
+## Packages
+
+| Runtime | Package | Import |
+| -------------------- | -------------------- | ------------------------------------------------ |
+| Python | `cua-driver` | `from cua_driver import CuaDriver` |
+| Node.js / TypeScript | `@trycua/cua-driver` | `import { CuaDriver } from "@trycua/cua-driver"` |
+
+Both packages are generated from the same Rust and UniFFI contract. Methods are
+asynchronous. Python uses `snake_case`; TypeScript uses `camelCase`.
+
+## Constructors
+
+| Python | TypeScript | Behavior |
+| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CuaDriver.create(options=None)` | `CuaDriver.create(options?)` | Creates the primary same-process runtime. No daemon, executable, or IPC is required. |
+| `CuaDriver.connect(socket_path=None)` | `CuaDriver.connect(socketPath?)` | Connects the same typed surface to a daemon. This is a compatibility and app-hosting path. |
+
+`DriverOptions` currently contains
+`claude_code_compatibility` / `claudeCodeCompatibility`, which defaults to
+`false`.
+
+`execution_mode()` / `executionMode()` reports the generated
+`DriverExecutionMode` value. The current enum variants are `Embedded` for the
+same-process runtime and `Daemon` for a socket-backed connection.
+
+## Lifecycle and metadata
+
+| Python | TypeScript | Result |
+| ------------------ | ----------------- | ------------------------------------------------------- |
+| `metadata()` | `metadata()` | Driver version, protocol version, and platform metadata |
+| `execution_mode()` | `executionMode()` | `DriverExecutionMode` |
+| `is_available()` | `isAvailable()` | Whether the runtime can serve calls |
+| `shutdown()` | `shutdown()` | Stops admission and awaits admitted work |
+
+In TypeScript, call `uniffiDestroy()` after `shutdown()` to release the binding
+handle. Python releases the handle during finalization, but applications should
+still await `shutdown()`.
+
+## Session methods
+
+| Python | TypeScript | Input |
+| ------------------- | ----------------- | ---------------------- |
+| `start_session` | `startSession` | `StartSessionInput` |
+| `get_session_state` | `getSessionState` | `GetSessionStateInput` |
+| `escalate_session` | `escalateSession` | `EscalateSessionInput` |
+| `end_session` | `endSession` | `EndSessionInput` |
+
+`StartSessionInput.capture_scope` / `captureScope` accepts `AUTO`, `WINDOW`, or
+`DESKTOP`. Capture scope is immutable for a live session. `AUTO` requires an
+explicit escalation before desktop tools are enabled.
+
+## Typed desktop methods
+
+| Python | TypeScript | Input |
+| --------------------- | ------------------- | ------------------------ |
+| `get_desktop_state` | `getDesktopState` | `GetDesktopStateInput` |
+| `get_screen_size` | `getScreenSize` | `GetScreenSizeInput` |
+| `get_cursor_position` | `getCursorPosition` | `GetCursorPositionInput` |
+| `move_cursor` | `moveCursor` | `MoveCursorInput` |
+| `click` | `click` | `ClickInput` |
+| `drag` | `drag` | `DragInput` |
+| `scroll` | `scroll` | `ScrollInput` |
+| `type_text` | `typeText` | `TypeTextInput` |
+| `press_key` | `pressKey` | `PressKeyInput` |
+| `hotkey` | `hotkey` | `HotkeyInput` |
+
+Use `list_tools_json()` / `listToolsJson()` and `call_tool()` / `callTool()` for
+the generic, platform-extensible tool surface. Prefer typed methods when one is
+available.
+
+## `ToolResult`
+
+Desktop methods return `ToolResult`.
+
+| Python field | TypeScript field | Meaning |
+| ----------------- | ---------------- | ------------------------------------------ |
+| `text` | `text` | Human-readable result text |
+| `images` | `images` | Returned images and MIME types |
+| `structured_json` | `structuredJson` | Structured platform result |
+| `is_error` | `isError` | Whether the tool reported failure |
+| `error_code` | `errorCode` | Stable tool error code, when present |
+| `verified` | `verified` | Whether post-action verification succeeded |
+| `degraded` | `degraded` | Whether a reduced-capability path was used |
+| `raw_json` | `rawJson` | Complete extensible result envelope |
+
+## Errors
+
+The generated `DriverError` variants are:
+
+- `Configuration`
+- `InvalidArguments`
+- `Transport`
+- `Protocol`
+- `Tool`
+- `Shutdown`
+
+Tool-level failures may also arrive as `ToolResult.is_error` / `isError`.
+Inspect the result before consuming images or structured fields.
+
+See [MCP tools](/reference/cua-driver/mcp-tools) for the agent-facing tool
+catalog and [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) for
+the architecture boundary.
diff --git a/docs/content/docs/tutorials/meta.json b/docs/content/docs/tutorials/meta.json
index d9757ea796..d36d302f42 100644
--- a/docs/content/docs/tutorials/meta.json
+++ b/docs/content/docs/tutorials/meta.json
@@ -1 +1,12 @@
-{ "title": "Tutorials", "icon": "GraduationCap", "pages": ["index", "drive-your-first-app", "your-first-cloud-sandbox", "create-your-first-lume-vm"] }
+{
+ "title": "Tutorials",
+ "icon": "GraduationCap",
+ "pages": [
+ "index",
+ "drive-your-first-app",
+ "your-first-cua-driver-python-app",
+ "your-first-cua-driver-typescript-app",
+ "your-first-cloud-sandbox",
+ "create-your-first-lume-vm"
+ ]
+}
diff --git a/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdx b/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdx
new file mode 100644
index 0000000000..1c6c44e03a
--- /dev/null
+++ b/docs/content/docs/tutorials/your-first-cua-driver-python-app.mdx
@@ -0,0 +1,82 @@
+---
+title: 'Your first Cua Driver Python app'
+description: 'Import Cua Driver as a same-process Python SDK and inspect the desktop.'
+---
+
+In this tutorial, you will import Cua Driver into a Python application, start a
+session, and read the desktop size. The driver runs in your Python process; you
+do not need to start a daemon.
+
+## Before you begin
+
+You need Python 3.10 or newer and a supported interactive macOS, Windows, or
+Linux desktop. On macOS, the Python host needs Accessibility and Screen
+Recording permission for the actions it performs.
+
+Create a virtual environment and install the published package:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install cua-driver
+```
+
+## Create the application
+
+Save this as `first_driver.py`:
+
+```python
+import asyncio
+
+from cua_driver import (
+ CaptureScope,
+ CuaDriver,
+ EndSessionInput,
+ GetScreenSizeInput,
+ StartSessionInput,
+)
+
+
+async def main() -> None:
+ driver = CuaDriver.create()
+ session = "first-sdk-app"
+
+ await driver.start_session(
+ StartSessionInput(
+ session=session,
+ capture_scope=CaptureScope.DESKTOP,
+ )
+ )
+ try:
+ metadata = await driver.metadata()
+ screen = await driver.get_screen_size(
+ GetScreenSizeInput(session=session)
+ )
+ print(f"cua-driver {metadata.driver_version}")
+ print(screen.text)
+ finally:
+ await driver.end_session(EndSessionInput(session=session))
+ await driver.shutdown()
+
+
+asyncio.run(main())
+```
+
+Run it:
+
+```bash
+python first_driver.py
+```
+
+The program prints the loaded driver version and the desktop dimensions. It
+also demonstrates the lifecycle every SDK application should own: create the
+runtime, start and end its sessions, then await `shutdown()`.
+
+## Next steps
+
+- [Use the SDK in process](/how-to-guides/driver/use-sdk-in-process) to capture
+ the desktop and select a capture scope.
+- [Python and TypeScript SDK reference](/reference/cua-driver/sdk-reference)
+ lists the typed methods, records, and errors.
+- [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) explains when a
+ daemon is useful.
diff --git a/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdx b/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdx
new file mode 100644
index 0000000000..46fad5c9f8
--- /dev/null
+++ b/docs/content/docs/tutorials/your-first-cua-driver-typescript-app.mdx
@@ -0,0 +1,75 @@
+---
+title: 'Your first Cua Driver TypeScript app'
+description: 'Import Cua Driver as a same-process TypeScript SDK and inspect the desktop.'
+---
+
+In this tutorial, you will import Cua Driver into a Node application, start a
+session, and read the desktop size. The driver runs in the Node process; you do
+not need to start a daemon.
+
+## Before you begin
+
+You need Node.js and a supported interactive macOS, Windows, or Linux desktop.
+On macOS, the Node host needs Accessibility and Screen Recording permission for
+the actions it performs.
+
+Create a project and install the published package:
+
+```bash
+npm init -y
+npm install @trycua/cua-driver
+```
+
+## Create the application
+
+Save this as `first-driver.mjs`:
+
+```js
+import {
+ CaptureScope,
+ CuaDriver,
+ EndSessionInput,
+ GetScreenSizeInput,
+ StartSessionInput,
+} from '@trycua/cua-driver';
+
+const driver = CuaDriver.create(undefined);
+const session = 'first-sdk-app';
+
+await driver.startSession(
+ StartSessionInput.new({
+ session,
+ captureScope: CaptureScope.Desktop,
+ })
+);
+try {
+ const metadata = await driver.metadata();
+ const screen = await driver.getScreenSize(GetScreenSizeInput.new({ session }));
+ console.log(`cua-driver ${metadata.driverVersion}`);
+ console.log(screen.text);
+} finally {
+ await driver.endSession(EndSessionInput.new({ session }));
+ await driver.shutdown();
+ driver.uniffiDestroy();
+}
+```
+
+Run it:
+
+```bash
+node first-driver.mjs
+```
+
+The program prints the loaded driver version and the desktop dimensions. It
+also demonstrates the lifecycle every Node application should own: create the
+runtime, start and end its sessions, await `shutdown()`, then release the
+generated binding handle with `uniffiDestroy()`.
+
+## Next steps
+
+- [Use the SDK in process](/how-to-guides/driver/use-sdk-in-process) to capture
+ the desktop and select a capture scope.
+- [Python and TypeScript SDK reference](/reference/cua-driver/sdk-reference)
+ lists the typed methods, records, and errors.
+- [SDK, MCP, and process hosting](/concepts/sdk-mcp-and-hosting) explains when a
+ daemon is useful.