Where a worker can run
The Where it runs step offers two homes, and the choice is about who operates the process.Komodor cloud
Komodor runs the worker and manages its replicas. Nothing to install, nothing to keep running.
This is the default for an agent deployed from the catalog.
Self-hosted
You run the worker in your own environment. Use this when the agent needs network access or data
locality you cannot grant from outside — and it is the default when you are authoring your own
agent.
Some catalog agents have only one possible home. When that is the case the step does not appear and
the target is decided by the agent itself.
What a worker needs from you
Exactly three values, all environment variables:
A handful of optional variables refine the deployment rather than enable it:
Nothing else is required. The worker binds no port and serves no HTTP — it dials the control plane
and receives work over that one outbound connection. There is no inbound firewall rule to open and
nothing to route traffic to, which is what lets a worker run behind NAT or inside a private cluster.
Deploy it
1
Get a worker token
From the wizard’s final step, from Settings → Agents, from the agent’s panel in Fleet, or
with
POST /api/v1/agents/worker-token.2
Run the worker
Start it however you run software, with the three variables set. For a Kubernetes deployment the
wizard renders the values file and the matching
helm install command for you — the release name
is the agent’s own name.3
Watch it register
The console polls for the agent’s first heartbeat and reports when it arrives. The agent moves
from draft to online.
4
Confirm the round trip
Use the agent’s self-check to make the control plane ask the worker a question and wait for its
answer. A worker that is offline, too old, or unresponsive still resolves — as a failure with a
reason, rather than hanging.
5
Run it once
Press Run agent and read the run. See Reading the first run.
What happens on first registration
Worth understanding once, because it explains every symptom you will ever debug here.1
It registers itself
The worker sends one registration message carrying the agent’s manifest — its card, its skills,
its declared triggers and labels. This is the only thing a worker ever says about itself, it is
sent once per process, and it is retried until it lands.
2
The agent becomes real
The control plane records the agent, ensures its identity as a principal, reconciles its declared
triggers and channel routes, and clears the draft. The agent’s status changes from draft to
online and it appears in Fleet.
3
It opens its channel
The worker holds an outbound connection open for work notifications. Until registration has
landed, opening that channel is refused — the SDK treats this as the expected start-up race and
simply retries, so a refusal in the first seconds of a worker’s life is normal, not a fault.
4
It pulls its boot secrets
After registering and before its first run, the worker fetches the credentials bound to its
agent that it needs at start-up.
5
It waits for work
When a run is available the control plane rings a doorbell rather than pushing the payload.
Workers respond by claiming the run, and the one that wins the claim receives the input, the
secrets, and any session state.
The claim model is why work is never lost to a dead worker. Ownership is decided by the claim, not by
the delivery, so if a worker dies mid-run the run is requeued for another one rather than
disappearing into a process that is no longer there.
What “enabled” means at this point
A newly registered agent is enabled, so its declared triggers can fire as soon as it is healthy. If that is not what you want on the first deployment, disable the agent before you start the worker and enable it once you have read a manual run. See Manage a deployed agent.Reading online and offline
Presence is the control plane’s question, not the worker’s claim: it pings each open channel every 30
seconds and the worker’s reply is what keeps it present. An idle worker sends nothing on a timer of
its own.
Two consequences worth knowing. A worker that dies without closing its connection takes up to 90
seconds to show as offline, so the badge lags reality slightly. And an idle worker that has gone
quiet is indistinguishable from one that died — by design.
Replicas
One worker process runs one agent, but an agent can be backed by several replicas, and each is tracked separately: its own identity, its own busy-or-idle state, and the cluster, namespace, and pod it runs in.- Run more replicas when the agent’s queue is growing. Read Queued and Oldest queued on the agent to decide.
- For a self-hosted agent, the Scaling step can declare autoscaling bounds — minimum and maximum replicas, and the queue depth each replica should absorb.
- For an agent Komodor hosts, replica count is managed for you.
Reading the first run
Open the run from the agent’s Run history. What you are checking, in order:- It started. A run that never leaves the queue means no worker claimed it — check that the agent is online.
- It could see what it needed. Missing tool calls, or tool calls that failed on authentication, point at a connection that is not attached or a credential that is not bound.
- It returned both channels. Structured fields for automation, and readable text for a person.
- It cost what you expected. Token usage is recorded per run, so a surprise here is visible immediately rather than at the end of the month.
When it does not come up
See Troubleshooting.
Next steps
Manage a deployed agent
Enable, disable, edit, archive, and read its activity.
Triggers & schedules
Give it a recurring schedule now that it is live.
Credentials & secrets
Bind the secrets it resolves at boot and per run.
Runs & evidence
Read the evidence trail behind that first run.