Run
Workers
A worker is a process you run that performs selected Mobius work inside your environment. Mobius coordinates the process; the worker uses your code, network, secrets, or local models.
Workers are the bridge when work cannot or should not run in Mobius Cloud. The connection is outbound from your environment, so Mobius does not need inbound access to your network.
When a worker is useful
Use a worker when an action or model must:
- Reach a private network or on-premises service.
- Use credentials that must stay in your environment.
- Run customer-owned code or a local model.
- Use hardware or capacity you manage.
- Work inside an isolated repository or filesystem.
If Mobius already provides the integration, use a hosted action. A normal Slack, GitHub, or Linear operation does not need a worker merely because it calls an external API.
Workers, actions, and jobs
These concepts describe different parts of the same handoff:
| Concept | Responsibility |
|---|---|
| Action | Names the operation a step or agent wants performed |
| Job | Records one unit of work waiting for or assigned to a worker |
| Worker | Runs the customer-owned code or model and reports the result |
| Run | Shows the larger process and what it is waiting for |
Most operators should start from the run. Look at the job or worker only when the run shows that customer-hosted work is waiting or failed.
Think in worker pools
A worker advertises the actions or model routes it can handle and how much work it can accept. Mobius sends it compatible jobs.
Begin with one broad pool. Split pools when there is a concrete reason:
- Slow actions should not consume capacity needed by fast actions.
- One class of work requires a GPU or private network.
- Production and staging must remain isolated.
- A managed environment should receive only its own work.
Extra queues and capability filters are operational boundaries. Add them when they express real capacity or isolation, not as default ceremony.
Use workers for local models
A worker can serve a model running in your environment while Mobius preserves the same agent session and run experience. This is useful for private models, specialized hardware, or model routes that should not leave your network.
The agent definition chooses the route; an online worker must advertise a matching provider and model. If a turn cannot find that route, check worker availability before changing the agent.
Managed and self-hosted environments
A self-hosted worker runs wherever you deploy it. A managed environment lets Mobius create an isolated workspace and worker for a run or agent.
Use self-hosted workers when you own the long-lived infrastructure or network. Use managed environments when the work needs a temporary checkout, filesystem, or isolated workspace without you operating the machine.
Monitor workers in the app
Open Runtime > Workers to see connected instances, available capacity, and the actions or models each worker can handle.
When a run waits for worker work, open the run timeline first. Then use the workers page to answer three questions: is a compatible worker online, does it have capacity, and is it in the right pool or environment?
Follow Connect a worker to establish the first connection and run a smoke test. The CLI command reference owns startup flags and readiness output. The SDK and interactive API reference own the worker protocol.
Next
- Connect a process with Connect a worker.
- Understand the diagnostic record with jobs.
- Define hosted and customer actions with actions.
- Choose a workspace with managed environments.