cua-driver Permission Modes: Standard, Bounded, Unrestricted

cua-driver enforces authorization inside the native runtime, after transport arguments are sanitized and before any platform action runs. CLI, MCP, direct SDK, private-worker, and service-backed calls all reach the same enforcement boundary. The permission mode is fixed at launch and belongs to the process that owns the runtime. A running daemon’s mode cannot be changed — stop it and start it again with the configuration you want.

Choosing a Mode

standard
bounded
unrestricted

The default mode. Routine observation, input, file transfer, isolated browser use, recording, and agent-adjustable settings run without Cua prompts. Residual boundaries (such as attaching to an existing Chromium profile) return a structured refusal unless they have an explicit grant or trusted host callback.Best for: normal local CLI and MCP use, development, interactive sessions.

cua-driver mcp
# or explicitly:
cua-driver serve --permission-mode standard

Deny-by-default. Only tools and resources listed in a launch-approved manifest may run. In-scope work is silent; out-of-scope work is denied. Requires a reviewed session policy file and a startup acknowledgement that it was reviewed.Best for: unattended agents, production gateways, embedded applications.

cua-driver serve \
  --permission-mode bounded \
  --session-policy ./cua-session.yaml \
  --approve-session-policy

Cua approval checks are bypassed after an explicit dangerous acknowledgement. Hard invariants and configured policy ceilings still apply. Requires --dangerously-bypass-approvals alongside --permission-mode unrestricted.Best for: disposable or fully trusted environments only.

cua-driver serve --dangerously-bypass-approvals

Unrestricted mode does not defend against prompt injection or unintended model actions. Use it only where you accept the full effect of every capability allowed by the built-in, managed, and user policy ceilings.

autonomous is a manifest compatibility alias for bounded. yolo is a configuration alias for unrestricted. New integrations should use the canonical names.

Setting the Mode Without CLI Flags

The mode is read once when the runtime that owns the driver starts. Launchers that cannot pass flags — cua-driver mcp owning its own runtime on Windows and Linux, a Windows Scheduled Task, or an embedding host — use equivalent environment variables:

CLI flag	Environment variable
`--permission-mode <mode>`	`CUA_DRIVER_PERMISSION_MODE=<mode>`
`--session-policy <path>`	`CUA_DRIVER_SESSION_POLICY_FILE=<path>`
`--approve-session-policy`	`CUA_DRIVER_SESSION_POLICY_APPROVED=1`
`--dangerously-bypass-approvals`	`CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1`

The variables accept 1, true, yes, or on for their boolean form.

Missing halves fail startup instead of silently downgrading to standard. unrestricted requires both CUA_DRIVER_PERMISSION_MODE=unrestricted and CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS=1. bounded requires both the policy file path and its approval variable.

CUA_DRIVER_SESSION_POLICY_FILE and CUA_DRIVER_SESSION_POLICY_APPROVED are rejected in standard and unrestricted mode, so a stale exported variable prevents startup rather than applying silently. These variables are trusted launch configuration on the same footing as CLI flags. An agent tool call can never set them.

What Standard Mode Allows

Standard mode preserves practical autonomous workflows without requiring explicit approval for routine actions.

Operation	Standard behavior
Observe windows, applications, and the desktop	Allow
Click, type, scroll, drag, and focus	Allow
Create and use a driver-owned isolated browser	Allow
Read visible page content through typed browser tools	Allow
Upload, download, screenshot, record, and replay validated paths	Allow
Change agent-adjustable cursor and image settings	Allow and audit
Terminate a process proven to have been launched by this runtime	Allow after process fingerprint revalidation
Terminate a foreign process	Deny
Run unbounded legacy page mutation scripts	Deny
Raise an operating-system permission prompt from an agent tool call	Deny
Attach to an existing logged-in Chromium profile	Require an explicit launch grant or trusted host authorization
Invoke an unknown risk-bearing operation	Deny

Attaching to Existing Chromium Profiles

An existing profile can contain live cookies and authenticated sites. Standard mode keeps attachment as an explicit boundary. Authorize it at daemon launch:

# For a newly launched MCP runtime:
cua-driver mcp --grant existing-profile

# For a long-running daemon:
cua-driver serve --grant existing-profile

--grant is repeatable and is trusted launch configuration. It cannot modify an already-running daemon — restart the daemon with the same grant when needed. Other valid authorization paths:

A bounded manifest that allows kind: existing_profile.
A DriverAuthorizationHost callback installed by an embedding application.
unrestricted mode with its dangerous acknowledgement.

An MCP transport marker, model-supplied boolean, environment variable, or ordinary tool argument is never an attachment grant.

Bounded Manifests

Bounded mode is deny-by-default. A tool must appear in allow.tools, and every resource crossed by that call must match the manifest. Manifest version 2 supports application identities, browser profile kinds, and directory roots:

version: 2
mode: bounded
expires_after: 8h
idle_timeout: 30m

allow:
  tools:
    - start_session
    - end_session
    - launch_app
    - list_windows
    - browser_prepare
    - get_browser_state
    - browser_navigate
    - browser_click
    - browser_type
    - browser_download
    - kill_app

resources:
  apps:
    - executable: /usr/bin/example-editor
      launch: true
      windows: all
      terminate: driver_launched

  browser:
    profiles:
      - kind: isolated
      - kind: existing_profile
    origins:
      - https://app.example.com

  files:
    read:
      - dir: /data/input
        recursive: true
    write:
      - dir: /data/output
        recursive: true

  desktop:
    display: false

On macOS, use bundle_id for an application identity. On Windows and Linux, use a canonical absolute executable path. windows: all allows windows owned by the matching application. terminate: driver_launched permits termination only when Cua proved that the current runtime launched that exact process instance.

Origin Scope Excludes Generic Input

resources.browser.origins binds the typed browser adapter only. A manifest that declares origins cannot also allow tools that reach a page around that adapter. The runtime refuses to start if it does:

authorization startup error: origin-scoped bounded manifests cannot allow
'click' because it bypasses the typed browser origin adapter

The excluded tools include click, double_click, right_click, drag, scroll, type_text, press_key, hotkey, set_value, get_window_state, get_desktop_state, get_accessibility_tree, verify_state, and page. Browser access and generic desktop input consequently belong to separate manifests and separate runtimes.

Version 1 manifests remain loadable, but version 2 is preferred for pre-launch and unattended workflows.

Authorization Stack

Every call must pass all applicable layers in order:

Hard invariants (self-targeting, protected-host checks).
The reviewed built-in tool and risk map.
Administrator policy from CUA_DRIVER_MANAGED_POLICY_FILE, when set.
User policy from CUA_DRIVER_POLICY_FILE, when set.
The bounded manifest, when the active mode is bounded.
A launch grant or trusted host authorization for a residual standard-mode boundary.

Each layer can only narrow access. No grant or permission mode can widen a managed or user policy.

Revocation

Revoke a single session:

cua-driver revoke --session research-1

Suspend the entire runtime generation (terminal; restart required for new calls):

cua-driver revoke --all

Session end removes its grants, browser bindings, launch provenance, recording state, and cursor. The ended session label remains tombstoned until an explicit start_session re-declares it.

Host Authorization and Embedding

An embedding application may install DriverAuthorizationHost to decide residual standard-mode requests itself. Cua supplies an attested, request-bound resource and digest; the host returns allow, deny, or cancel. An optional DriverActivityObserver receives content-free action, authorization, grant, and session events. Events never contain page text, typed input, file contents, screenshots, or raw resource identities. When no launch grant or host callback exists, a residual boundary returns a structured authorization_required refusal — no Cua-owned modal is shown.

Security Boundary

The host owns the permission mode, manifest, launch grants, and any human consent UX. Agent tools cannot change them. Same-user native code, malware, and automation with control of the same desktop are outside cua-driver’s security boundary. Cua can prevent an agent from forging its own tool arguments, but it cannot turn an ordinary desktop window into a secure desktop.

Cua Driver

Sandbox SDK

Lume

Cua Bench

cua-driver Permission Modes: Standard, Bounded, Unrestricted

Choosing a Mode

Setting the Mode Without CLI Flags

What Standard Mode Allows

Attaching to Existing Chromium Profiles

Bounded Manifests

Origin Scope Excludes Generic Input

Authorization Stack

Revocation

Host Authorization and Embedding

Security Boundary

Build docs developers (and LLMs) love

Cua Driver

Sandbox SDK

Lume

Cua Bench

Documentation Index

​Choosing a Mode

​Setting the Mode Without CLI Flags

​What Standard Mode Allows

​Attaching to Existing Chromium Profiles

​Bounded Manifests

​Origin Scope Excludes Generic Input

​Authorization Stack

​Revocation

​Host Authorization and Embedding

​Security Boundary

Build docs developers (and LLMs) love

Choosing a Mode

Setting the Mode Without CLI Flags

What Standard Mode Allows

Attaching to Existing Chromium Profiles

Bounded Manifests

Origin Scope Excludes Generic Input

Authorization Stack

Revocation

Host Authorization and Embedding

Security Boundary