Skip to main content

Run Agents in Your Own Cluster

By default a background agent on the Willow Agents platform runs on Willow's infrastructure. The agent harness is the alternative: a Helm chart your infrastructure team installs once, after which every agent you create in Willow gets a dedicated pod in your own Kubernetes cluster.

Nothing about how you work with an agent changes. You still write its prompt, attach its tools and skills, and select Deploy in the dashboard. What changes is where the agent's reasoning happens and whose model key pays for it.

How it compares​

You wantUse
Agents that run on Willow's infrastructure with no setup at allWillow Agents. Each session uses a session credit.
Agent inference and tool execution inside your own network, on your own model keys, without writing a runtimeThe agent harness, described here.
A runtime you build and operate yourselfCustom, where your code calls Willow.

The harness sits between the last two: your infrastructure, but not your code. It registers as a custom-managed platform type, so Willow pushes each agent and each message to it — you never implement the harness API yourself.

Because agent pods reach the Willow gateway to call tools, the harness works with any Willow deployment model. Paired with a hybrid or on-prem gateway, no agent traffic leaves your network at all.

Willow stays the source of truth​

This is the part worth internalizing before you set it up: the cluster holds no agent configuration. Everything that defines what an agent is and can do lives in Willow and is pushed to the harness when you deploy.

What you configure in WillowWhat appears in the cluster
System promptThe agent's instructions file
ToolsAn MCP configuration pointing at the gateway, scoped to that agent
SkillsThe skill files, mounted into the pod
RulesAppended to the agent's instructions; enforcement stays with the gateway and guards
Model and step limitsThe pod's runtime settings
Active / disabled toggleThe pod is scaled to one replica or to zero

Two consequences follow. An agent is fully reproducible from its Willow definition, so losing the cluster loses no configuration. And nobody can quietly grant an agent a capability by editing something in Kubernetes — capabilities only come from Willow, so the agent's permission boundary is the same one you see in the dashboard.

Check which model provider the harness was installed with

The one setting that isn't purely yours to choose is the model. The harness is installed with a single model provider key, so selecting a model from a different provider makes that agent fail on its first run. Ask your infrastructure team which provider they configured before picking a model outside it.

Every tool call still goes through the Willow gateway using the agent's own credentials. The agent pod holds no API keys for Slack, GitHub, or anything else. Guards, policies, and audit logging apply exactly as they do to any other agent.

Setting it up​

1. Install the chart​

Your infrastructure team installs the harness in a Kubernetes cluster and gives you two things: the harness's public hostname, and the shared bearer token it was configured with. See Background Agents on Kubernetes.

2. Register it as an agent type​

Open Manage → Machine Users → Background Agents, select the gear icon to reach Background Agent Settings, and choose Add custom type:

FieldValue
NameWhatever you want it called in the create dialog, for example Kubernetes Harness.
Sync endpointhttps://<harness-host>/willow/sync
Message endpointhttps://<harness-host>/willow/message
Auth headerAuthorization
Bearer tokenThe shared token from your infrastructure team.

Select Create, and the type appears in Agent Types alongside the built-in platforms.

The token is what protects the harness

The harness rejects any call whose bearer token doesn't match. If it's wrong, deploying an agent fails with a 401 — see Troubleshooting.

3. Create an agent on it​

Create a background agent and pick the new type as its platform. Write its system prompt, assign its tools, attach any skills, and select Deploy.

Willow sends the full agent definition to the harness, which brings up a pod for it. A first deploy usually takes under a minute. Use Test on the agent's Overview tab to run it once and confirm it responds.

What changes day to day​

Almost nothing, which is the point:

ActionEffect in the cluster
Deploy / Deploy changesThe agent's pod is created or updated with the new definition
Editing the prompt, tools, or skillsTakes effect on the next deploy
Toggling the agent to disabledIts pod is scaled to zero; nothing is deleted
Toggling it back to activeIts pod comes back
Deleting the agentIts pod and all of its Kubernetes objects are removed
Firing a trigger or sending a messageRouted to the agent's pod and run there

Sessions and their events — messages, tool calls, and results — are recorded by the harness, so conversation history survives pod restarts. Each conversation is correlated by its session key exactly as on any other platform.

Deploying rotates the agent's secret

As on every platform, deploying writes fresh gateway credentials, which invalidates any plaintext secret you were holding. See Authentication.

Troubleshooting​

Most problems at this level are the connection between Willow and the harness. Anything below that — pods, images, databases — is in the deployment guide's troubleshooting table.

SymptomCause
Deploy fails with 401The bearer token on the agent type doesn't match the one the harness was installed with.
Deploy fails with 400 Invalid agent.sync payloadThe Sync endpoint URL is wrong. It must end in /willow/sync, and the Message endpoint in /willow/message.
A trigger fails with 404 Agent not synced to this harnessThe agent was never deployed. Select Deploy first.
A trigger fails with 409 Agent is not readyThe agent is disabled, or its last deploy failed. Ask your infrastructure team to check the agent's status on the harness.
The agent deploys but every tool call failsThe harness is pointed at the wrong gateway, or the agent's credentials are stale. Re-deploy to reissue them.
On this page