Set Up AI Worker

Install the packages, choose where the worker middleware will run, then connect it to Magento. We recommend Node for local development and Cloudflare Workers for a managed production setup. Your own production Node service is another hosting choice.

1. Install the Packages

A Hyvä Commerce subscription is required for the Commerce packages. Configure Composer access for your subscription, then install the integration and providers you need.

For CMS content and image generation with Gemini, for example:

composer require hyva-themes/commerce-module-ai-worker hyva-themes/commerce-module-ai-worker-cms hyva-themes/magento2-module-ai-gemini

For CMS translation with DeepL:

composer require hyva-themes/commerce-module-cms-ai-translations hyva-themes/magento2-module-ai-deep-l

Install only the provider packages you use. They supply credentials, models and PHP protocol adapters; the open-source base AI module supplies the shared contracts. Hyvä CMS and the Media Gallery have their own package requirements.

Complete normal Magento deployment, including bin/magento setup:upgrade, configuration-cache refresh, DI compilation and admin static deployment as required by your environment. The CMS integration includes a CMS admin style fragment; rebuild the shared admin styles when installing it. Restart long-running consumers after module updates.

Worker version 1.0.0 includes all runtime files in one worker module. Translation-only installations using Direct PHP can go straight to Translate CMS Fields. For worker features, continue below.

2. Choose Where the Worker Will Run

The PHP fallback is available before an external worker is configured, when Enable PHP Worker is Yes and the worker secrets and provider credentials are saved. It works even when Enable External Worker is No. It is not the recommended deployment for streaming or production. Long requests occupy Magento PHP processes and can be interrupted by PHP or proxy timeouts. See PHP Fallback for its limits.

3. Prepare Magento

Open Stores → Configuration → Hyvä AI → AI Worker:

1. In General, set Enable External Worker to Yes for Node or Cloudflare. For PHP-only use, leave it No.
2. Choose Generate Secrets. Keep the two displayed values securely for the Node or hosted worker setup, then save the configuration.
3. Save your provider API key under Hyvä AI → Settings, in that provider's group. Provider keys stay in Magento.
4. In PHP Worker and Backup, choose whether Enable PHP Worker should remain Yes. This independently enables PHP for standalone use or backup during an external outage. It uses your store's PHP capacity. Choose No for external-only operation.

The section is visible to the Administrators role. A custom role sees it only once Stores → Settings → Configuration → Hyvä AI Worker Section is ticked under System → Permissions → User Roles.

With AI Worker CMS installed, the AI Translation, Generation and Image Generation groups move from Hyvä AI → Settings to Hyvä AI → Hyvä CMS, which a custom role sees only with Hyvä AI CMS Section ticked. To run generations, a custom role also needs Content → AI Worker, plus AI Jobs under it for the job list and Start from previous run. Grant the New Hyvä CMS Permissions to Custom Roles lists every AI resource.

4. Deploy and Connect the Worker

For PHP-only use, skip external deployment and run Test Connection after saving. To connect Node or Cloudflare:

1. Follow Running the Worker, using the files from your installed package.
2. Configure the worker with the two matching secrets and the origin settings below.
3. Save its HTTPS address in External Worker URL, without /v1/stream or another endpoint suffix.
4. Save Magento configuration, then run Test Connection. It checks the external worker and enabled PHP backup separately.

Confirm that the external worker passes. A working PHP backup does not mean the external service is configured correctly. Test Connection does not spend provider tokens; it checks the worker connection, secrets and access back to Magento.

The external worker takes priority when available. PHP can take over if it cannot start a request. Accepted work is not generated again by the backup, and provider errors still need fixing. See the settings table.

5. Enable the Feature

Follow Feature Configuration. Under Hyvä AI → Hyvä CMS, enable Generation and choose a model. Configure Image Generation separately if needed. Choose AI Worker in the feature's Run requests using setting, or inherit a general AI Worker choice.

The Direct PHP execution option is for short requests through the base AI module. It does not use the worker or its fallback settings.

Generate a small draft and review it. Test images and background jobs separately if you use them; these checks do use your AI provider.

Settings for Your Developer

Configure an External Runtime

Keep provider API keys in Magento. Keep external runtime secrets outside Composer-managed directories and source control.

Leave Worker Callback Base URL empty if the worker can reach the default secure storefront URL. Otherwise, enter a reachable HTTPS Magento base URL. This controls request retrieval and result delivery without changing storefront or admin URLs. Local Node usually needs no tunnel; a hosted service needs a Magento endpoint reachable from that service.

Magento checks both URLs on save, in the admin and through bin/magento config:set. Each must be an absolute HTTPS URL without credentials, a query string or a fragment. Plain HTTP is accepted only for localhost, 127.0.0.1 and [::1].

Magento also accepts HYVA_AI_WORKER_TOKEN_SIGNING_SECRET and HYVA_AI_WORKER_KEY_ENCRYPTION_SECRET from its environment. These override saved values. A developer can provision missing secrets with:

bin/magento hyva:ai-worker:secrets:generate --if-missing

To export the effective secrets for an external runtime:

bin/magento hyva:ai-worker:env

Check the Network Paths

In containers, localhost refers to that container. Check from each caller's environment. See Operations and Troubleshooting, including Basic-auth staging and background job requirements.