Guides

This guide starts the worker included with the mobius CLI, creates one test loop, and proves that the worker can complete its action.

You will use two terminals:

• The worker terminal uses a worker-only API key and stays open.
• The authoring terminal uses your normal CLI login to create and run the test loop.

Keeping those credentials separate matters. A worker key can claim work, but it should not be able to edit loops.

Before you start

• Install and sign in to the CLI.
• Use an account that can create loops and worker credentials.
• Know the project handle. This guide uses ridgeline.

Replace ridgeline with your project handle everywhere it appears below.

1. Create the worker credential

In the app, select the project and open Runtime > Workers. Click New worker.

1. Name the API client ridgeline-worker.
2. Keep the Worker system role selected.
3. Name the first key primary.
4. Click Create worker.
5. Copy the full mbx_... key when it appears. Mobius shows it only once.

In the worker terminal, set that key and the project:

export MOBIUS_API_KEY="mbx_..."
export MOBIUS_PROJECT="ridgeline"

PowerShell uses this form:

$env:MOBIUS_API_KEY="mbx_..."
$env:MOBIUS_PROJECT="ridgeline"

Do not export the worker key in the authoring terminal.

2. Start the stock worker

In the worker terminal, run:

mobius worker --queues default --concurrency 1

The stock worker is a test-ready worker bundled with the CLI. It includes small actions such as print, json, time, random, and fail.

Wait for both startup messages before continuing:

level=INFO msg="starting worker" api_url=... project=ridgeline ...
level=INFO msg="worker registered" worker_instance_id=... ...

The second line means Mobius can send work to this process. Leave the worker terminal open.

3. Create the test loop

In the authoring terminal, save this file as worker-smoke-test.yaml:

schema_version: "1"
name: worker-smoke-test
description: Prove that the stock worker can complete one action.
concurrency: allow
triggers:
  - key: manual
    kind: manual
    enabled: true
steps:
  - id: print
    name: Print message
    kind: action
    config:
      action_name: print
      parameters:
        message: "Hello from Ridgeline Dental."

The print action uses the default worker queue, so the loop does not need a separate queue setting.

Create the loop:

mobius loops create --project ridgeline --file worker-smoke-test.yaml --fields id,name,status --output json

Copy the returned loop id.

4. Start a run

Replace <loop-id> with that ID:

mobius runs start <loop-id> --project ridgeline --fields id,status --output json

Copy the returned run id. The initial status may be queued or running.

The worker terminal should show the handoff and printed message:

job claimed ... action=print ...
Hello from Ridgeline Dental.
job complete ... action=print ...

5. Confirm the result

After the worker reports job complete, inspect the run:

mobius runs get <run-id> --project ridgeline --fields id,status,result --output json

Success looks like this:

{
  "id": "run_...",
  "status": "completed",
  "result": {
    "print": "Hello from Ridgeline Dental."
  }
}

The worker also appears as active under Runtime > Workers, with the test job shown as its latest completed work.

If it does not complete

• No worker registered message: read project and api_url in the starting worker log. If either is wrong, correct MOBIUS_PROJECT or pass the intended --api-url, then start the worker again.
• The loop cannot find print: keep the worker connected while creating the loop, then confirm that the worker row under Runtime > Workers lists the print action.
• The run keeps waiting: open Runtime > Workers and confirm that the worker is active, accepts default, and has a free slot.
• The worker claimed the job and returned an error: open the run and read the action step error before retrying.

For production, replace the stock action with your own SDK handler, keep the Worker role on its API client, and run the worker process under a service manager that restarts it after a crash. See Workers for routing, capacity, local models, and duplicate-safe action guidance.