Try now →

Routing - Your Machine or the Cloud

How Wonda decides whether an action runs on your own computer or on the account's hosted browser, and how to pin it.

Two places an action can run

The same API call can execute in one of two places:

  • Your machine - the Wonda desktop app is running, so the action runs in the Wonda Automation Browser (WAB) on your computer, on your own IP, with the account's cookies staying on your device.
  • The cloud twin - a hosted browser session for that persona, behind dedicated mobile or residential IPs, which can run when your machine is off.

You do not pick this per call. The backend routes each action, and an API client gets the same routing an MCP client would.

Engine policy

Routing follows your account's engine policy:

PolicyBehaviour
auto (default)Prefer your machine when its relay is online; fall back to the cloud twin if the persona is cloud-capable and the account has the Premium cloud-twin entitlement
my_machineOnly run on your machine; fail rather than fall back to the cloud
cloudAlways run on the hosted twin, even when your machine is online

my_machine is the setting to choose when an account must never be touched from hosted infrastructure.

auto does not guarantee the work continues when your laptop closes. Cloud fallback needs both a cloud-capable persona and Premium cloud-twin entitlement; without them a local persona returns relay_offline or paid_plan_required instead of moving to the cloud.

Transport: cookies or WAB

Independently of where an action runs, each action has a transport - how it talks to the platform:

  • cookies - a direct authenticated request using the persona's stored session. Fast, cheap, and used for most reads.
  • wab - a real browser page driving the platform's UI. Slower, and required for anything the platform does not expose to a plain request.

Every action has a sensible default, listed in the Action Reference. Override it per call when the action supports both:

curl -X POST \
  "https://api.wondercat.ai/api/v1/twin/sessions/natty/actions/x/mentions?via=wab" \
  -H "Authorization: Bearer $WONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

via accepts cookies or wab. Anything else is rejected with command_not_allowed and reason: "invalid_payload". Forcing wab on a read is occasionally useful when the cookie path is being rate-limited by the platform; forcing cookies on an action that genuinely needs a browser will fail.

Pinning the cloud twin

Add engine=cloud to run on the hosted twin regardless of the account policy:

POST /twin/sessions/{persona}/actions/{platform}/{action}?engine=cloud

This exists so a caller that means "run this in the cloud" cannot be silently routed to a live local relay.

Related