Model worker

Configure a MODEL_WORKER for managed or local model capability: operations, model and provider identity, modelLocality, and MODEL_WORKSTATION / MODEL_INVOKE companionship.

How To Use

Author a worker with type MODEL_WORKER when migrating an existing managed or local model config. Put model, modelProvider, and modelLocality on the worker so authored identity and locality win over operator defaults. Declare operations with typed inputs and outputs for pre-dispatch compatibility. Keep descriptive context in the body. Bind the worker from a MODEL_WORKSTATION companion; use MODEL_INVOKE when the invoke-style companion applies. For new factories, prefer INFERENCE_WORKER instead of MODEL_WORKER. Model workers are not AGENT_WORKER backends: they do not own agentTools or skipPermissions.

Discriminator: type = MODEL_WORKER

MODEL_WORKER requires a MODEL_WORKSTATION companion. MODEL_INVOKE is a compatible companion for invoke-style model calls. Prefer INFERENCE_WORKER with INFERENCE_RUN for new one-shot inference backends.

Schema reference

The embed below shows the live Worker base definition with MODEL_WORKER overlay applicability. Shared fields include identity, model routing, operations, modelLocality, and openCodeAgent. Excluded fields belong to agent-loop, script, or hosted-poller families and must not appear on this variant. Open the full Factory schema reference for exhaustive field lookup rather than copying contract text into this page.

Worker

object

A reusable worker definition that tells the factory how a workstation should execute work, such as through a model-backed agent or a script.

additionalPropertiesfalse (closed)

Fields

agentToolsagentToolsOptionalAgentWorkerToolsConfigExcluded
Explicit agent-loop tool policy for AGENT_WORKER definitions. Omit or set policy DISABLED to run agent loops without advertising or executing tools.
argsargsOptionalarrayExcluded
Additional command arguments passed to the configured command.
authauthOptionalHostedWorkerAuthExcluded
Hosted-worker authentication contract. V1 hosted workers accept only auth.secretRef.
bodybodyOptionalstring
Inline worker instructions or script body when the worker is authored directly in factory config.
commandcommandOptionalstringExcluded
Command to execute when this worker runs through a command or script provider.
descriptiondescriptionOptionalNameValue
Optional localized customer-facing explanation of this worker.
executorProviderexecutorProviderOptionalWorkerProviderExcluded
Execution mechanism. Use `ACP` for ACP-backed workers and put the configured integration identity (for example `cursor-acp`) in modelProvider. `SCRIPT_WRAP` remains the command-wrapper compatibility value; legacy named executor identities remain accepted during migration.
ididOptionalstring
Optional durable public identifier for this worker. When present, graph and layout references should use this id instead of the mutable name.
linearlinearOptionalHostedLinearWorkerConfigExcluded
Provider-specific configuration for the built-in hosted LINEAR worker.
modelmodelOptionalstring
Model identifier to request from the configured model provider when this worker uses model execution.
modelLocalitymodelLocalityOptionalWorkerModelLocality
Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution.
modelProvidermodelProviderOptionaloneOf
Canonical provider identity used for model routing and provider diagnostics, or an exact invocation-parameter placeholder such as `${modelProvider}`. For `executorProvider: ACP`, this names the configured ACP integration, such as `cursor-acp`. Extension identities use lowercase standardized syntax; built-in values such as `CLAUDE` and `CODEX` remain compatibility conveniences.
namenameRequiredstring
Worker name referenced by Workstation.worker.
operationsoperationsOptionalModelOperation[]
Provider-agnostic model operations that this worker can execute, including named input and output slots.
providerproviderOptionalHostedWorkerProviderExcluded
Built-in hosted provider identity when this worker uses repository-owned hosted execution.
reasoningEffortreasoningEffortOptionalReasoningEffort
resourcesresourcesOptionalResourceRequirement[]
Resource capacity this worker requires before it can be dispatched.
skipPermissionsskipPermissionsOptionalbooleanExcluded
When true, bypasses permission checks for providers that support permission gating.
stopTokenstopTokenOptionalstring
Marker that tells model-oriented workers where to stop generated output when the provider supports it.
timeouttimeoutOptionalstring
Optional Go duration that caps one worker execution attempt.
typetypeOptionalWorkerType
Worker implementation family to instantiate for this definition.

Full Factory schema reference

Examples

Use the minimal valid example when reviewing a MODEL_WORKER with local TTS capability. The misuse example shows agentTools on a model worker—agentTools belongs on AGENT_WORKER and fails validation on MODEL_WORKER.

Minimal valid MODEL_WORKER:

{
  "name": "local-tts-model",
  "type": "MODEL_WORKER",
  "model": "OMNIVOICE_Q4_K_M",
  "modelProvider": "CODEX",
  "modelLocality": "LOCAL",
  "resources": [
    {
      "name": "omnivoice-cache",
      "capacity": 1
    }
  ],
  "operations": [
    {
      "name": "TTS",
      "inputs": [
        {
          "name": "text",
          "required": true,
          "contentTypes": [
            "TEXT"
          ]
        },
        {
          "name": "voice",
          "contentTypes": [
            "JSON"
          ]
        }
      ],
      "outputs": [
        {
          "name": "audio",
          "contentTypes": [
            "AUDIO"
          ]
        }
      ]
    }
  ],
  "body": "Legacy managed local TTS model capability."
}

Incompatible misuse — agentTools on MODEL_WORKER (rejected):

{
  "name": "local-tts-model",
  "type": "MODEL_WORKER",
  "model": "OMNIVOICE_Q4_K_M",
  "modelProvider": "CODEX",
  "modelLocality": "LOCAL",
  "agentTools": {
    "policy": "ENABLED"
  },
  "operations": [
    {
      "name": "TTS",
      "inputs": [
        {
          "name": "text",
          "required": true,
          "contentTypes": [
            "TEXT"
          ]
        }
      ],
      "outputs": [
        {
          "name": "audio",
          "contentTypes": [
            "AUDIO"
          ]
        }
      ]
    }
  ],
  "body": "Legacy managed local TTS model capability."
}

agentTools is an agent-loop field. Validation rejects it on MODEL_WORKER. Use AGENT_WORKER for prompt-rendered agent loops.