Reference

A worker is a program that connects your Mobius organization to a machine that can do work for it. The worker waits for action calls or local-model requests, does that work on the machine where it is running, and sends the result back to Mobius.

The connection starts from the worker. You do not need to open an inbound firewall port or let Mobius connect directly to your network.

Mobius provides a worker in the mobius CLI. It includes small actions such as print, json, and fail for tests. Build a worker with a Mobius SDK when you need your own action handlers.

Decide whether you need one

Use a worker when the work must run on a machine you control:

• It needs a private network or an on-premises system.
• A credential or sensitive input must stay on that machine.
• You want to run your own code or AI model.
• The work needs particular hardware or a local filesystem.

The worker can keep local credentials, code, and source data on its machine. Action parameters, model requests, and returned results still pass through Mobius. Do not put a secret in an action parameter just because a worker will run the action.

Do not add a worker just to call a supported online service. If Mobius already provides the action, let Mobius run it. A worker is another process that your team must deploy, monitor, update, and restart.

How work reaches a worker

The handoff has five parts:

1. An agent calls a worker-backed action, or requests a local model.
2. Mobius creates a worker job in the organization. A job is the handoff record, not something you author yourself.
3. Mobius finds a connected worker that lists the requested action or model. An optional queue or managed environment can narrow that match.
4. The worker claims the job. The agent's turn waits while the worker runs it.
5. The worker returns a result or error. Mobius records it on the job and lets the waiting turn continue.

The session is the record you care about. The worker job is one internal handoff inside a turn. Start with the transcript when you inspect or troubleshoot work.

Queues and capacity

A queue is an optional routing label. A job assigned to a named queue can only go to a worker that accepts that queue. The stock CLI worker accepts every queue when you omit --queues.

A queue is not an access-control boundary. Any worker in the organization that accepts all queues can claim the job. To reserve a queue for one machine, start every worker with an explicit queue list and make sure only that machine lists the reserved queue. Use separate organizations when workers run for customers or operators who must not see one another's job inputs and results.

The worker-backed action definition selects the queue for an action call. A worker model route can select one for a local model request. A run or step that uses an existing managed environment carries that environment selection into the job.

Start without custom queues, or use only default. Add another queue when you have a current routing requirement, such as:

• Only one machine can reach the target network.
• GPU work must stay away from ordinary actions.
• Production and test work must use different machines.
• One customer's work must stay on a dedicated machine.

Each worker also reports a concurrency limit. For example, a worker with concurrency 5 can hold five jobs at once. Open Runtime > Workers to compare its busy jobs with that limit.

Your machine or a managed environment

Run your own worker when you own the machine, credentials, or private-network access. You are responsible for keeping that process available.

A managed environment is an isolated workspace that Mobius provisions and operates, including its worker process. You do not start that worker yourself. Use a managed environment when the work needs a temporary workspace but does not need a machine that you operate.

Run a local model

The stock worker can serve models installed in a local Ollama instance:

mobius worker --ollama

The worker discovers installed models when it starts and lists them in Runtime > Workers. Restart it after adding or removing an Ollama model. Select one of those advertised models on the agent.

When worker work is stuck

Open the run and find the waiting or failed step. Then open Runtime > Workers and check, in order:

1. Is any worker active in the organization?
2. Does an active worker list the required action or model?
3. If the work uses a named queue or environment, does that worker match it?
4. Does the worker have a free concurrency slot?
5. If it claimed the job, what error did the worker return?

When a worker disconnects and its job claim expires, Mobius automatically makes the unfinished job available for another attempt. A change in another system may already have happened. If a custom action creates or changes something outside Mobius, include a stable request identifier in its input and reject a duplicate before repeating the change.

Use Connect a worker to run the stock worker and complete one test action. The CLI command reference covers normal startup and connection logs. If you are implementing a worker instead of using an SDK, use the Jobs API reference for the exact claim, heartbeat, and result contract.