Local API and desktop tasks
Last updated:Nov 13, 2026
The desktop app comes with two automation tools. The local API lets scripts, the command line and AI assistants on this computer work on devices through the desktop app, with no token to issue. Automation tasks need no code: they run a list of actions by hand or on a schedule. Both work only while the desktop app is open and signed in.
Local API
Under Account settings → Automation in the desktop app you'll find the Local API card:
- the "Turn on the local API" switch, on by default;
- the address, which listens on this computer only (
http://127.0.0.1:<port>, usually port 53070); - the token, hidden by default, which you can show, copy, or reset after confirming;
- where the credentials file
cli-auth.jsonlives.
A new token is made every time the desktop app starts and every time you reset it. The local API only accepts requests from this computer that carry the token, and it refuses requests while the desktop app is locked because it couldn't confirm it is online. If the switch is greyed out, your role doesn't have the Local API permission.
From the command line
Add --local to any command line command to go through the local API. It reads the credentials file by itself, so there's nothing to sign in to:
yunyoo --local devices
yunyoo --local --device env:123 observe screenshot --out a.png
yunyoo --local --device env:123 ui tap --text OK
yunyoo --local tasks list
The local API works on environments on this computer's local node, and on cloud-node environments through the desktop app. Environments on the local node are handled directly by this computer, which is faster.
From an AI assistant
yunyoo --local mcp
This serves the MCP tools on this computer. Set up your assistant as described in MCP, using --local mcp as the arguments. From desktop app 1.1.0 the tool list follows your account's permissions, and the power tool env_power is available only this way.
From other programs
Other programs can call the local API directly with the token, for example to list devices:
curl -s -H "Authorization: Bearer $CPD_TOKEN" http://127.0.0.1:53070/api/devices
Put the token from the card in CPD_TOKEN. The token changes on every start, so long-running programs should read it from the credentials file each time.
Automation tasks
Open Automation in the desktop app's sidebar and click New task:
- Give it a name and choose how it runs: By hand or On a schedule. Schedules use a cron expression, or you can pick a common rule; the page lists the next five run times, in this computer's time zone.
- Choose devices. Each chosen device runs the task once and offline ones are skipped. With none chosen, the task runs on the first online device (environments on local nodes first, then environments on cloud nodes), or you can switch it to run on every online device.
- Write the actions: a JSON array with one action per item. Pick templates from the insert menu, or click Record in a viewer, turn on "Record steps for a task" in the viewer toolbar, and your taps, swipes and typing become actions.
[
{ "action": "screenshot", "args": { "localPath": "/Users/me/shots/home.png" } },
{ "action": "ui-action", "args": { "action": "tap", "point": { "x": 0.5, "y": 0.5 } } },
{ "action": "wait", "args": { "ms": 1000 } },
{ "action": "wp:app", "args": ["launch", "com.android.settings"] },
{ "action": "wp:macro", "args": ["run", "/Users/me/flows/login-smoke.yaml"], "timeoutSec": 600 }
]
- Each action has
actionandargs, and optionallytimeoutSec(60 seconds by default, at most 3600) andcontinueOnError(whether to go on after this step fails; off by default). A task holds up to 200 actions, and positions are fractions of the screen from 0 to 1. - Built-in actions:
screenshot,ui-dump,ui-action,shell,push,pull,install,wait. - Actions starting with
wp:run the command line that ships with the desktop app, on this computer. The commands aredevices,observe,ui,run,fileandapp, plusmacrofrom desktop app 1.1.0; writeargsas a list, and it becomes the arguments after the command. Usewp:macroto run a flow macro. If the flow can't match the screen at some step, the run counts as failed and the reason names the step and what went wrong. - Saving checks every action and points out which one is wrong and why.
After saving, click Run now in the list or wait for the schedule. Run history lists every run with its result, what started it, and its log.
Scheduled tasks run only while the desktop app is open: nothing runs while it is closed or the computer sleeps, and missed runs are not made up later. Runs that come due while the desktop app is locked are recorded as skipped. The "Run scheduled tasks" switch under Account settings → Automation pauses all scheduled tasks; running a task by hand still works. A task never runs twice at the same time on the same device.
Approvals and taking over (desktop app 1.1.0 and later)
High-risk steps run through the local API (clearing app data, uninstalling apps, running commands, and steps involving payments, messages or accounts) may also need your approval. The desktop app then shows a system notification when its window isn't in front; approve or decline on the Confirmations and reports tab of the Automation page. The command line and AI assistants wait for your decision, and once you approve, the step runs once.
When a built-in task action such as ui-action or shell hits a step that needs approval, that step fails instead of waiting. To make a task wait for you at that step, write it as a wp: action (such as wp:ui or wp:run); the command line then waits for your decision within the step's timeout.
While you have taken over a device in the viewer, local API actions are refused until you click Hand back at the top of the viewer. Every step run through the local API is added to the platform's run records, which you can see under Confirmations and reports; text you type is not uploaded.
