Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs(cua-driver): publish SDK guides and architecture (#2499)
Francesco Bonacci63049ff598ce
diff --git a/docs/README.md b/docs/README.mdindex 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.jsonindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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 automaticallimport { 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.jsonindex 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.mdxnew file mode 100644index 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.mdxindex 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.jsonindex 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.mdxindex 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 rolesThe 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 listensThe 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 froOn 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 lonThe 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.mdxnew file mode 100644index 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.jsonindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.