> For the complete documentation index, see [llms.txt](https://docs.zenml.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenml.io/kitaru/core-concepts/workers.md). # Workers The process that runs replays, imports, and evaluators as subprocesses in your environment, so your code and data never leave your systems. Nothing in Kitaru executes on the server. Replays, imports, and evaluator runs are **tasks**; a **worker** is the process that claims tasks from the server and runs each one as a subprocess in *your* environment, with *your* virtualenv, credentials, and network. The server coordinates, your infrastructure executes, and session payloads are read from the server your team already hosts. Start one wherever your agent's code can run: ```bash kitaru worker start --concurrency 4 ``` The worker registers itself, polls for pending tasks, heartbeats while work is in flight, and reports results. Stop it with Ctrl-C: the first signal drains in-flight tasks, a second one exits immediately. ## What a worker executes | Task kind | What the subprocess is | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent` | Your agent, started from the [agent version's](/kitaru/core-concepts/agents-and-sessions.md) run spec command; this is how replays, experiment runs, and on-demand session runs re-execute your real code | | `evaluator` | A registered [evaluator](/kitaru/core-concepts/evaluators.md) plugin, run against one session | | `importer` | A registered importer parsing an uploaded trace payload into sessions | Evaluator and importer plugins declare their own dependencies (PEP 723 inline metadata for script plugins, an exact pin for package plugins), and the worker builds each an isolated environment via `uv`. Agent tasks run your command as-is, in the working directory and environment the agent version declares, plus the [secrets](/kitaru/running-in-production/secrets.md) it references. The worker hands each subprocess its context through environment variables: `KITARU_API_URL` and a `KITARU_API_TOKEN`, a bearer token scoped to that one task and attempt, with your broader `KITARU_API_KEY` stripped from the child environment. It also provides `KITARU_TASK_ID` to link the recorded session to the task, and `KITARU_REPLAY_ID` when the run is a replay, which is how the adapter knows to apply overrides and answer tool calls from the recording. The worker itself authenticates once with your API key and holds a worker-scoped token it renews on its own; see [Authentication & API keys](/kitaru/running-in-production/authentication.md). ## Scoping workers By default a worker claims any pending task. Narrow it when environments differ: ```bash # only imports and evaluations; no agent code runs here kitaru worker start --claim importer --claim evaluator # only tasks for a specific agent version's environment kitaru worker start --claim agent= # drain one job, then exit; useful in CI kitaru worker start --job-id ``` Every option is also an environment variable with the `KITARU_WORKER_` prefix (`KITARU_WORKER_CONCURRENCY`, `KITARU_WORKER_SCOPE__CLAIMS`, …), so a containerized worker can be configured without flags. Deployment patterns, including long-running workers on Kubernetes and one-shot workers in CI, are in [Workers in production](/kitaru/running-in-production/workers.md). Check what's alive: ```bash kitaru worker list kitaru worker get ``` `kitaru worker list` shows live workers, add `--include-stale` for the rest. Names are labels shared by any number of workers, so `kitaru worker get` takes an id from that listing. A worker record exposes `last_seen_at`, the time of its last observed heartbeat, and `live`, the server's current liveness calculation. These are observations, not assignment guarantees: a worker can become unavailable after its last heartbeat, and a live worker may not match a task's scope or win its claim. The native MCP server exposes the same list and exact-UUID get operations through the read-only `kitaru_registry_read` tool. It cannot register, update, delete, or control workers. A worker that stops heartbeating loses its tasks: the server requeues them for the next worker (or fails them at the retry cap), so a crashed pod never strands a replay. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.zenml.io/kitaru/core-concepts/workers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.