Guides

This guide starts the worker included with the mobius CLI and proves that the worker can complete one action call.

You will use two terminals:

• The worker terminal uses a worker-only API key and stays open.
• The calling terminal uses your normal CLI login to invoke the action.

Keeping those credentials separate matters. A worker key can claim work, but it should not be able to change your organization's setup.

Before you start

• Install and sign in to the CLI.
• Use an account that can invoke actions and create worker credentials.

1. Create the worker credential

In the app, 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:

export MOBIUS_API_KEY="mbx_..."

PowerShell uses this form:

$env:MOBIUS_API_KEY="mbx_..."

Do not export the worker key in the calling 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=... queues=... ...
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. Confirm Mobius can see its actions

In the calling terminal:

mobius catalog list-actions --output json | grep print

print appears in the catalog only while a worker offering it is connected. If it isn't there, Mobius has nothing to hand the job to, and the next step will fail rather than wait.

4. Call the action

mobius actions invoke print \
  --input '{"message": "Hello from Ridgeline Dental."}' \
  --output json

The worker terminal should show the handoff and the printed message:

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

And the calling terminal gets the result:

{
  "status": "completed",
  "job_id": "job_...",
  "output": "Hello from Ridgeline Dental."
}

That's the whole round trip: your machine ran the code, and Mobius has the result.

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

5. Let an agent call it

The point of a worker is that an agent can reach it. Open Build > Agents, open an agent, and add print in the Tools section.

Now ask that agent, in a conversation, to print something. It calls the action, the worker runs it, and the result comes back inside the agent's turn. The session transcript is where you read what happened; the worker job is one internal handoff inside that turn.

If it does not complete

• No worker registered message: read api_url in the starting worker log. If it is wrong, pass the intended --api-url or set MOBIUS_API_URL, then start the worker again. If it is right, check that MOBIUS_API_KEY holds the worker key.
• print is not in the catalog: keep the worker connected, then confirm that the worker row under Runtime > Workers lists the print action.
• The call 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: read the error on the invocation before retrying. mobius actions list-invocations shows past calls.

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.