App Builder · Ep 11: what runs on your machine, and what needs a deploy

Step 1 of 4

An aio app deploy to Stage takes minutes, and every typo costs another one. So I took everything built in episodes 1 to 10 and tried each piece three ways: fully on my machine, as local code talking to the deployed Stage workspace, and deployed. It was one session, with a local Adobe Commerce (PaaS, on Warden) and the Ep 8–10 Stage workspace.

Three results were not what I expected:

  • State works from localhost. Adobe's troubleshooting page says it doesn't. It did, both from a plain Node script and inside an action under aio app dev. Files failed, as the page says.
  • aio app dev ignores raw-http: true. The signed webhook from Ep 7 can't pass its own signature check locally.
  • wskdebug failed twice and changed the deployed action. After its own restore, provide-api-key=true was still on it.

You’ll need

  • The app from episodes 1 to 10, at the ep11-local-testing tag
  • aio CLI (I used 11.2.0) signed in to a Stage workspace, with the repo's .env
  • A local Adobe Commerce (PaaS) with the eventing, webhooks and Admin UI SDK modules, for the webhook and Admin UI rows

Read the grid first

RUN means I ran it in this session. "Ep N" means an earlier episode proved it and I didn't repeat it. DOCS ONLY means nobody here ran it.

PieceOn your machineYour code, Stage servicesOnly a deploy shows
Unit testsRUN: npm test (fakes)––
Web actions, require-adobe-authRUN: aio app dev; the auth check only looks for the headersEp 9: the deployed sequence answers 401 without a tokenthe validator sequence
StateRUN: works, against the docsRUN: script with the namespace credentials–
FilesRUN, fails: ERROR_BAD_CREDENTIALSRUN, fails: sameFiles from Runtime
Database StorageRUN: works, on the workspace's real databaseRUN: scriptthe post-deploy index hook (Ep 4)
Croncall the action by hand; no triggers under aio app devRUN, fails: wskdebugRUN: the alarm fired the action
Log forwardinglogs in the terminalaio app logs (Ep 5)forwarding (Ep 5)
Commerce eventsRUN: a saved payload to the handlerRUN: a journaling pull, dry runDOCS ONLY: delivery; retries measured in Ep 6
WebhooksRUN, fails: raw-http ignoredRUN, refused: webhooks:dev:run to the deployed action (likely the key)the signed path (Ep 7)
API MeshRUN: aio api-mesh run, one batched callsources are the deployed actionsthe edge cache (Ep 8)
Admin UI SDKRUN: the menu from aio app dev through local testing; page not openedEp 9–

On Adobe Commerce as a Cloud Service two cells change: you test webhooks in the Admin instead of with webhooks:dev:run, and Admin UI SDK local testing is PaaS only.

Run it all on your machine

aio app dev runs one extension at a time. This app has two, so plain aio app dev stops with "You can only run one at the time, please select which extension to run with the '-e' flag".

aio app dev -e application              # actions on https://localhost:9080
aio app dev -e commerce/backend-ui/1    # the Admin UI extension

The actions run in local Node with a self-signed certificate. Calling them showed four things:

  • require-adobe-auth is a header check. With no headers the call gets 401. With Authorization: Bearer dummy and any x-gw-ims-org-id, it passes. The deployed sequence checks the token; the local one doesn't.
  • Non-web actions are served too, with a warning that the call will fail without credentials when deployed. So the cron action can be called over HTTP; without COMMERCE_BASE_URL it answers 500, as on Stage.
  • A process variable beats .env. ERP_API_URL=http://127.0.0.1:9/orders aio app dev -e application pointed the order handler at a dead port without touching .env. A query parameter does not override an action input.
  • Database Storage writes to Stage. Under aio app dev aio-lib-db connected to the workspace's real database. The saved order event I fed to events/order-placed left a real failed claim row there. Delete your test rows.

Cron has no local trigger: the aio app dev source has no trigger or alarm handling, so the alarm never fires.

Webhooks are where local testing stopped. Local Commerce reached the local action through https://host.docker.internal:9080 with sslVerification="false" on the hook. cart-check verifies Commerce's signature over the raw body, which raw-http: true hands it as __ow_body on Runtime. aio app dev ignores that annotation: it treats an action as raw only when it says web: 'raw'. So the body is parsed into params, __ow_body is missing, and every call from Commerce is refused. I left the code alone, because changing it to pass a local test would change what runs on Stage.

The mesh runs locally from aio api-mesh:init (the first npm install took about 10 minutes) and aio api-mesh run mesh.json --port 9000. The Ep 8 query made one batched reviews call with all 17 SKUs, as on Stage. Both sources answer Cache-Control: no-store and no Cache-Status header came back, so this run can't say whether the local server caches. The edge cache stays a deploy-only check. Ctrl+C left the mesh's worker processes holding the port, and I had to stop them by hand.

The Admin UI SDK's local testing does not point at aio app dev directly. Its "Local Server Base URL" replaces Adobe's App Registry, so something local has to answer like the registry. Adobe's sample is a small server.js; I used a 10-line stand-in. With that, the admin module (run from PHP in the container, not in a browser) read the registration action from aio app dev and built the "Stuck orders" menu under Apps. One more catch: only the registry call turns off SSL verification, and aio app dev's certificate is self-signed.

Run your code against the Stage workspace

Called from a plain Node script with the namespace credentials in .env, the three storage services behaved as they did under aio app dev: State and the database worked, Files refused. Both probes are in the repo. node dev/run-ep11/state-probe.js (add --db for Database Storage) runs the calls from Node. The ep11-probe action runs the same calls under aio app dev; it is gated by EP11_PROBE_ENABLED, and non-web so a deploy can't expose it.

For events, I created a journaling registration on the Stage workspace and read it from a local script:

node dev/run-ep11/journal-pull.js --order EP11-TEST-0001          # dry run: lists only
node dev/run-ep11/journal-pull.js --order EP11-TEST-0001 --post https://localhost:9080/api/v1/web/events/order-placed

The dry run got a token, called the journal and read 0 events, because I placed no order. --post only sends to localhost. Delete the registration afterwards.

For webhooks, the same webhooks:dev:run from the local Commerce reached the deployed cart-check. The first call timed out at the hook's 2000 ms (a cold start); the second answered in 0.7 s and was refused. Likely reason: my local signing key isn't the one in the deployed PUBLIC_KEY. The signed path itself was proven in Ep 7.

wskdebug is built for this case: it swaps the deployed action for an agent that forwards each activation to a container on your machine. On I/O Runtime it failed for me twice. Version 1.4.0 (npm's default, which Adobe's Commerce troubleshooting page lists as not working) got a 502 from its own polling. Version 1.2.0, listed as working, installed its agent, said "Ready, waiting for activations!", and died the same way on the first invoke.

Here is the mistake that taught me the most. After the first failure I deleted wskdebug's backup action by hand, thinking the action was back. It wasn't. The agent's annotations were still on it, including provide-api-key=true, which hands the namespace key to the action. An update with the original code didn't remove them, because Runtime merges annotations on update. The second time wskdebug restored the action itself, and the annotations stayed anyway. Both times I deleted the action and created it again from a copy saved before the run. If you try wskdebug, save the action first and check its annotations afterwards:

aio rt action get ops/stuck-orders --save-as before.zip
aio rt action get ops/stuck-orders | grep -A2 -E 'wskdebug|provide-api-key'

The same Adobe page also says wskdebug can't be used with aio-lib-state or aio-lib-files, and stuck-orders uses both.

Keep the deploy for what only a deploy shows

I enabled stuckOrdersSchedule for ten minutes. The every15Minutes trigger fired at the quarter hour and ops/stuck-orders ran 9 seconds later. Then I disabled the rule again. That firing, a real I/O Events delivery with its retries, the signed webhook, the mesh's edge cache and the validator sequence in front of require-adobe-auth actions are the checks I still deploy for. Everything in the grid's first two columns I now try before I deploy.

Tested on: one session on 21 Nov 2026 with aio-cli 11.2.0, a local Adobe Commerce (PaaS, developer mode) and the Ep 8–10 Stage workspace. Every Stage change was undone and checked: the journaling registration and test rows deleted, the alarm rule disabled again, and ops/stuck-orders recreated with the code, annotations and parameters it had before.

Not tested: a live order through I/O Events to a local handler, the Admin UI page in the admin iframe (the menu was read, the page was not opened), the signed webhook under aio app dev, and the mesh cache with a cacheable source. The current list is in the repo README.

Done!

You can now tell, before you deploy, which checks your machine can answer and which ones need Stage.

> code for this episodeGitHub · ep11-local-testing →Agent hand-off →

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More