Daemon
Run, stop and inspect the daemon, its sessions and autostart.
Run, stop and inspect the daemon, its sessions and autostart.
| Command | Description |
|---|---|
cua-driver serve | Run Cua Driver as a long-running daemon. |
cua-driver stop | Ask the running daemon to exit gracefully. |
cua-driver status | Report whether a Cua Driver daemon is running. |
cua-driver sessions | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
cua-driver sessions list | List live sessions. |
cua-driver revoke | Revoke one or all live authorization/session scopes. |
cua-driver autostart | Manage platform-native daemon autostart. |
cua-driver autostart enable | Register the autostart entry. |
cua-driver autostart disable | Remove the autostart entry. |
cua-driver autostart status | Print whether autostart is registered and running. |
cua-driver autostart kick | Start the autostart entry now without re-logging. |
Every command also accepts the global options.
cua-driver serve#Run Cua Driver as a long-running daemon.
The daemon owns per-process state such as accessibility snapshots, recording state, and cursor overlay state.
cua-driver serve [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--pid-file | path | Override the pid-file path on Unix targets. | |
--permission-mode | string | standard | Immutable agent authorization mode: standard, bounded, or unrestricted. |
--grant | string | Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile. | |
--capability-manifest | path | Optional narrow-only tool/resource ceiling; required in bounded mode. | |
--session-policy | path | Deprecated alias for capability-manifest. | |
--host-bundle-id | string | Advisory host bundle id label echoed in check_permissions output (embedded mode). | |
--cursor-theme | string | cua.default | Installed cursor theme id for the agent cursor overlay. |
--cursor-reduced-motion | string | auto | Agent cursor motion: auto follows the OS setting, on forces still frames, off allows animation. |
--glide-ms | number | Override the agent cursor glide duration, in milliseconds. | |
--dwell-ms | number | Override how long the agent cursor dwells after a click, in milliseconds. | |
--idle-hide-ms | number | Override how long an idle agent cursor stays visible, in milliseconds. | |
--experimental-pip-geometry | string | Size and optional top-left origin of the experimental preview window: WxH or WxH+X+Y (default 480x360, top-right of the main display). | |
--claude-code-computer-use-compat | boolean | false | Select the Claude Code computer-use compatibility surface (forwarded by mcp when it launches the daemon). |
--experimental-pip | boolean | false | Show a small always-on-top window with the latest post-action screenshot and a one-line label (macOS only). |
--dangerously-bypass-approvals | boolean | false | Select unrestricted mode and acknowledge its risk. |
--approve-capability-manifest | boolean | false | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
--approve-session-policy | boolean | false | Deprecated alias for approve-capability-manifest. |
--no-permissions-gate | boolean | false | Skip the macOS first-launch permissions gate. |
--embedded | boolean | false | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
--no-overlay | boolean | false | Disable the agent cursor overlay for this daemon. |
--experimental-history | boolean | false | Admit the encrypted local Computer History early preview for this daemon launch. |
Examples
# Run the daemon in the foreground
cua-driver serve
# Start a bounded daemon with a reviewed capability manifest
cua-driver serve --permission-mode bounded --capability-manifest manifest.yaml --approve-capability-manifest
# Run without the agent cursor overlay
cua-driver serve --no-overlaycua-driver stop#Ask the running daemon to exit gracefully.
cua-driver stop [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--expected-pid | number | Stop only if the daemon's process id is this one (a positive integer). |
Examples
# Ask the running daemon to exit
cua-driver stopcua-driver status#Report whether a Cua Driver daemon is running.
cua-driver status [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--pid-file | path | Override the pid-file path on Unix targets. |
Examples
# Check whether the daemon is running
cua-driver statuscua-driver sessions#List content-free lifecycle summaries for sessions owned by the daemon runtime.
cua-driver sessions [OPTIONS] [COMMAND]Without a subcommand, runs cua-driver sessions list.
| Flag | Type | Default | Description |
|---|---|---|---|
--socket | string | Override the daemon socket or named-pipe path. | |
--json | boolean | false | Emit the machine-readable session summary. |
Examples
# List live sessions as JSON
cua-driver sessions --jsoncua-driver sessions list#List live sessions. The default subcommand.
cua-driver sessions listExamples
# List live sessions
cua-driver sessions listcua-driver revoke#Revoke one or all live authorization/session scopes.
Revocation is deny-only and never accepts an approval token.
cua-driver revoke [OPTIONS]| Flag | Type | Default | Description |
|---|---|---|---|
--session | string | Exact session id to stop and revoke. | |
--socket | string | Override the daemon socket or named-pipe path. | |
--all | boolean | false | Stop and revoke every live session. |
Examples
# Stop and revoke one session
cua-driver revoke --session 3f9c2a
# Stop and revoke every live session
cua-driver revoke --allcua-driver autostart#Manage platform-native daemon autostart.
Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance.
cua-driver autostart <COMMAND>Examples
# Check the autostart entry
cua-driver autostart statuscua-driver autostart enable#Register the autostart entry.
cua-driver autostart enableExamples
# Start the daemon at every logon
cua-driver autostart enablecua-driver autostart disable#Remove the autostart entry.
cua-driver autostart disableExamples
# Remove the autostart entry
cua-driver autostart disablecua-driver autostart status#Print whether autostart is registered and running.
not-registered is emitted only when Task Scheduler explicitly reports that the named task does not exist. If the task cannot be inspected, the command exits non-zero and reports permission-denied or unknown together with the original diagnostic.
cua-driver autostart statusExamples
# Check the autostart entry
cua-driver autostart statuscua-driver autostart kick#Start the autostart entry now without re-logging.
cua-driver autostart kickExamples
# Start the entry now
cua-driver autostart kick| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. call and direct tool invocations exit with the daemon's result code (1 on a tool error); update --apply passes through the installer's status. |
2 | Invalid input: tool arguments that are not valid JSON, an unknown mcp-config client, or an update --apply refused on a local development install. |
64 | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example revoke without exactly one of --session or --all, or an authorization flag passed to mcp). |